Le DSL des blocs

Vue d'ensemble

Un bloc est un dossier web/configurations/components/<id>/ (ou fragments/<id>/). Quand ce dossier contient un tree.json dont la racine porte une clé primitive, la page rend le bloc à partir de cet arbre : sa forme, ses textes, son état, ses calculs, ses validations et ses actions sont du JSON, lu par un moteur commun à tous les projets. Le DSL est le vocabulaire fermé de ce moteur. Une clé qu'il ne connaît pas est ignorée, sans message d'erreur.

Ce que rend un tree.json : le bloc de commande d'une démo de pâtisserie, avec le panier, le créneau de retrait et le récapitulatif.

Une page monte le bloc depuis son structure.json, par l'id du dossier : un nœud component lit components/<id>/, un nœud fragment lit fragments/<id>/.

Bloc statique, bloc interactif

Deux moteurs rendent un arbre. Un bloc statique est rendu sur le serveur, sans JavaScript, et ne comprend que les marqueurs de texte {slot}. Un bloc devient interactif dès que sa racine porte logic, state, actions, onMount, derive, watch ou effects, qu'un de ses nœuds porte on, when, unless ou repeat, ou qu'un fichier logic/<id>/bindings.json déclare des appels. Il passe alors au moteur interactif, qui s'exécute dans le navigateur, et tout ce qui suit s'applique.

Les nœuds de l'arbre

Un nœud est un objet JSON. La racine de tree.json est un nœud comme les autres, qui porte en plus les clés de comportement décrites dans La racine du bloc.

Les types de nœuds

Les primitives

Les attributs d'un wrapper passent par une liste fermée : className, id, role, hidden, inert, tabIndex, title, disabled, les data-* et aria-*, style (un objet, filtré comme un styleJson) et, sur un élément SVG, ses attributs de géométrie (viewBox, d, fill...), plus ref et region. Les autres sont écartés sans erreur. Écrivez l'ARIA avec un tiret (aria-label, aria-pressed) ; la forme ariaLabel est convertie.

Un champ dont value est lié sans événement input ou change est rendu en lecture seule. Checkbox, Radio et SliderCheckbox se pilotent par checked, pas par value.

Embarquer un autre bloc

Un nœud fragment monte un bloc par son name : un bloc du projet (son id) ou un bloc fourni par Kubbler (son nom, par exemple StripeCheckoutForm). props.__variantId choisit un autre id que le nom, et les autres props remplacent son options.json. pass lui transmet des propriétés résolues ; une valeur { "action": ... } y devient une fonction qui exécute cette action dans le bloc parent, la valeur reçue étant lisible en $arg. name et __variantId acceptent un $ref.

Règles d'écriture de l'arbre

• Chaque nœud porte un primitive (une chaîne) et un id au format [A-Za-z0-9_-]+, unique dans l'arbre.
• Profondeur maximale : 64 niveaux. Au plus 2000 nœuds.
• children est une liste. Les clés __proto__, constructor et prototype sont refusées.
• L'Atelier vérifie ces règles à chaque écriture du fichier : un tree.json ou un slots.json qui les viole est refusé (400).

Les textes : slots et dictionnaires

Un texte du bloc ne s'écrit pas en clair dans l'arbre. L'arbre porte un marqueur {slot}, slots.json déclare le slot, et le dictionnaire de chaque langue porte sa valeur.

La clé de dictionnaire d'un slot est <slot>_<suffixe>. Le suffixe est le dernier segment de l'id du bloc après son dernier tiret : le bloc orderFlow donne _orderFlow, un bloc order-flow donnerait _flow. Les dictionnaires du bloc sont fusionnés dans celui de la page quand la vue le liste dans son structure.json.

Les slots dans l'Inspecteur : chaque texte du bloc avec sa clé <slot>_<suffixe> (titleA_homeHero, subtitle_homeHero) et sa valeur.w/[wsSlug]/p/[slug]?sel=ui:{id}

Résolution d'un marqueur

• {x}, quand x est un slot du bloc : le moteur lit la clé x_<suffixe>. Si elle manque, un bloc interactif affiche le defaultValue du slot, un bloc statique affiche need_trads.
• {x}, quand x n'est pas un slot : le moteur lit la clé x telle quelle dans le dictionnaire de la page ; si elle manque aussi, il affiche x.
• {$chemin} : la clé est la valeur lue en $chemin, puis la même résolution s'applique. C'est ainsi qu'un bloc affiche un libellé choisi par sa configuration.

Dans la démo d'épicerie, options.json liste les rayons ; chaque rayon nomme son titre par un id de slot (aisleFl). L'arbre écrit {$a.title} dans la boucle : la valeur aisleFl est un slot, donc le texte affiché est celui de la clé aisleFl_productList.

Un texte se pose dans props.text, ou comme chaîne dans children quand il s'intercale entre des nœuds. Une chaîne peut mêler texte fixe, valeurs et clés : "x${it.quantity}", "${p.name}, ${v.label} : {addedToast}".

Les valeurs et les opérateurs

Toute valeur de l'arbre (une prop, une condition, un argument d'action) est résolue au rendu, ou au moment où l'action s'exécute, selon sa forme :

Le scope

Le scope est l'ensemble des noms qu'un $chemin peut lire. Du plus faible au plus fort (un nom plus fort masque le même nom plus faible) :

• store : la mémoire du site, lue en $store.<nom>Reducer.<chemin>.
• locale : la langue de la page, lue en $locale.
• Les clés de options.config, puis de options.fragments : config.aisles se lit $aisles.
• Le retour du hook de comportement, s'il existe.
• Les atomes de state.
• Les valeurs de derive, calculées dans l'ordre où elles sont écrites.

S'y ajoutent selon le contexte : les variables d'un repeat (l'élément, index, n, isFirst, isLast, count), $event dans une action, le résultat nommé par as, $prev et $next dans un watch, $arg dans une action passée par pass.

Les opérateurs

Un opérateur est un objet qui a exactement une clé, et cette clé est un nom d'opérateur. Ses arguments s'écrivent en liste (un argument seul peut s'écrire sans liste) et sont résolus avant l'appel, donc un opérateur peut en contenir un autre. when, unless, where et le when d'une action tiennent une liste vide pour fausse ; partout ailleurs, et donc dans not, and, or et if, une valeur est vraie au sens de JavaScript, et une liste vide y est vraie : testez une liste avec empty. La liste des opérateurs est fermée :

La racine du bloc : état, calculs, validations

La racine de tree.json porte, en plus de ses clés de nœud, le comportement du bloc :

state

Chaque atome se lit $atome et s'écrit par l'action set. Un nom à points écrit dans un atome objet ("set": "form.email"). La validation écrit le message d'un champ dans l'atome <champ>Error ; les démos le déclarent à "".

derive

Un derive appelle une fonction nommée avec des arguments résolus dans le scope (args peut être une valeur seule). Les derive sont calculés dans l'ordre où ils sont écrits, et chacun lit ceux qui le précèdent : un derive qui lit un derive déclaré plus bas reçoit undefined, que les fonctions numériques comptent pour 0. Une fonction inconnue donne undefined. La liste des fonctions est fermée :

Un simulateur de tarif enchaîne ses calculs du haut vers le bas ; waste est un booléen, que mul compte pour 1 ou 0 :

validate

validate associe à chaque champ (un atome de state) une liste de règles, essayées dans l'ordre : la première qui échoue donne le message du champ. Une règle s'écrit { "rule": "<nom>", "args": [...], "error": "<clé>" } ; avec "when": <condition>, elle ne s'applique que si la condition est vraie. La validation ne s'exécute que par une action (validate ou validateAll) : elle vide <champ>Error pour chaque champ vérifié, puis y écrit le texte de la clé error, ou la clé elle-même si le dictionnaire ne la porte pas.

Le comportement en JavaScript

Quand le DSL ne suffit pas, un hook useLogic complète le bloc. Le moteur cherche web/configurations/logic/<id>/index.js (l'id du bloc), puis le comportement fourni par Kubbler que nomme la clé logic. Le hook reçoit { name, id, options, dictionary, args } ; ce qu'il renvoie entre dans le scope : une valeur se lit $nom, une fonction s'appelle par le verbe call ou par son nom. Un hook de quelques lignes suffit à exposer un paramètre de route :

onMount et watch

onMount exécute une action une seule fois, dans le navigateur, après le premier rendu, avec le scope de ce rendu. watch associe une valeur à une action : à chaque rendu la valeur est relue, et l'action s'exécute quand elle a changé (jamais au montage), avec $prev (l'ancienne valeur) et $next (la nouvelle). C'est ainsi qu'un bloc réagit à un changement de la mémoire du site.

Au montage, la boutique choisie n'est peut-être pas encore connue : skipEmpty n'envoie pas un storeId vide, et le watch relance la lecture des créneaux dès que currentId change.

refs déclare des références d'éléments ("refs": ["field"]), qu'un nœud reçoit par "ref": "$field". effects y attache un effet nommé ({ "fn": "autofocus", "ref": "field" }), exécuté au montage et relancé quand sa valeur when change.

Conditions, listes et événements

when et unless

when rend le nœud si sa valeur est vraie, unless si elle est fausse. La valeur est n'importe quelle valeur du DSL : un $ref ou un opérateur. Un nœud masqué n'est pas rendu du tout, ni lui ni ses enfants.

repeat

repeat rend le nœud une fois par élément de over. Une valeur qui n'est pas une liste ne rend rien.

Chaque itération expose l'élément sous son nom, index (à partir de 0), n (à partir de 1), isFirst, isLast et count (le nombre d'éléments rendus). "unless": "$isLast" sur un nœud d'un group répété pose un séparateur entre les éléments.

on

on associe un événement à une action. Le moteur branche ces événements, et $event.value y vaut :

input et change branchent le même gestionnaire React (onChange) : sur un champ texte, les deux partent à chaque frappe. Un set sans to écrit $event.value : { "set": "email" } sur input garde l'atome à jour, et la seconde étape efface le message d'erreur.

Pour réagir à une seule touche, gardez l'action par une condition : { "when": { "eq": ["$event.value", "Enter"] }, "then": "submit" } sur keydown.

Les actions

Une action prend une de trois formes :

• Une chaîne : le nom d'une action de actions ; à défaut, une fonction du comportement, appelée sans argument.
• Une liste : des actions exécutées l'une après l'autre ; chaque étape attend la fin de la précédente, appel à l'API compris.
• Un objet : un ou plusieurs verbes.

Dans un objet, les verbes s'exécutent toujours dans cet ordre, quel que soit l'ordre d'écriture : when, validate, validateAll, set, toggle, forEach, call, dispatch, fetch, reset, navigate, toast, puis then.

Un objet arrêté par when, validate ou validateAll ne va pas plus loin, mais la liste qui le contient continue. Une validation écrite seule dans une étape n'empêche donc pas l'étape suivante : écrivez la validation et l'envoi dans le même objet.

Ce que lit une chaîne d'actions

Une action lit le scope du rendu où l'événement est parti. Un set change l'état pour le rendu suivant, pas pour les étapes suivantes de la même chaîne : $atome y garde l'ancienne valeur, validate aussi, et $store reste l'état d'avant une dispatch. Pour enchaîner sur un résultat, nommez-le avec as ; pour réagir à un changement de la mémoire, utilisez watch.

Un enregistrement complet : les clés vides de with listées dans skipEmpty ne sont pas envoyées, le résultat est nommé created, et la suite affiche un message puis ouvre la fiche créée, ou pose un message d'erreur.

La mémoire du site et l'API du projet

La mémoire du site (les stores Redux) se déclare dans web/configurations/stores/stores.json. Chaque entrée crée une mémoire nommée <nom>Reducer.

Un thunk appelle une route de l'API du projet et renvoie sa réponse telle quelle, { status, body } : il ne lève pas d'erreur sur un statut 4xx ou 5xx. Le fichier actions/<thunk>/index.js décide de ce que la mémoire garde.

Depuis l'arbre

Un arbre lit la mémoire par $store.<nom>Reducer.<chemin> ($store.cartReducer.items) et se rend à nouveau quand elle change. Il agit sur elle par le verbe dispatch :

Le résultat d'un thunk, nommé par as, a la forme { result: { status, body }, thunkDuration } : lisez $res.result.status et $res.result.body. Il vaut undefined si l'appel a échoué (réseau coupé) ou a été annulé ; la suite de l'action s'exécute quand même, avec une branche else pour ce cas.

Appeler l'API du projet

• La route existe dans l'API du projet : ici POST /orders/submit, dans le groupe orders.
• stores.json déclare le thunk dans cases, avec ses deux fichiers thunks/ et actions/. Le thunk vise l'entrée endpoint1 de api.json et le chemin de la route.
• L'arbre lance { "dispatch": { "store": "ordersReducer", "thunk": "submitOrder", "with": { ... } } }, puis lit la réponse par as ou par $store.ordersReducer.

Où arrive la commande : la collection orders dans les Données de l'Atelier, une commande ouverte dans l'Inspecteur.w/[wsSlug]/p/[slug]?sel=data:col:orders

Le verbe fetch appelle une route sans thunk : path (résolu), endpoint (une entrée de api.json, endpoint1 par défaut), method, params (la query string), body et into. La réponse est écrite dans l'atome nommé par into, avec <into>.loading et <into>.error. GET lit ; toute autre méthode part en POST, avec body ou, à défaut, tout l'état local du bloc. Un fichier web/configurations/logic/<id>/bindings.json peut déclarer ces appels hors de l'arbre, { "calls": [{ "endpoint", "path", "method", "into", "trigger" }] } : sans trigger (ou avec "mount"), au montage ; sinon après l'action du même nom.

Exemple complet : un parcours de commande

La démo de pâtisserie vend des gâteaux à retirer en boutique. Son bloc orderFlow (web/configurations/components/orderFlow/) enchaîne le panier, le choix d'un créneau, les coordonnées et le paiement, sans JavaScript propre au bloc. La page commander le monte par un nœud component d'id orderFlow.

Le bloc orderFlow inspecté dans les Mécanismes : son tree.json, 15 variables d'état, 3 actions, et les deux routes qu'il appelle (listSlots, submitOrder).w/[wsSlug]/p/[slug]?sel=map:behavior:orderFlow

L'état et le calcul

La racine déclare les atomes du formulaire (date, pickupAt, pickupLabel, customerName, email, phone, note), un atome de message par champ validé, trois messages d'étape (cartError, pickupError, submitError) et deux atomes de copie (snapshot, snapshotTotal). Un seul calcul : minD, la date du jour plus deux jours, posée en min du champ de date pour imposer 48 heures de délai. La section La racine du bloc montre l'état complet et la validation de customerName et email.

Le panier vient de la mémoire

Le panier n'est pas dans l'état du bloc. Il vit dans la mémoire cart, gardée dans le navigateur (persist: true) et remplie par l'action synchrone addItem depuis l'accueil et la page des gâteaux. Le bloc la lit (repeat sur $store.cartReducer.items, total $store.cartReducer.total formaté en euros) et la modifie par ses actions synchrones incrementItem, decrementItem et removeItem, avec "layer": "statics" et l'id de la ligne en arg.

Le créneau

Le champ de date écrit date, puis appelle l'action pickDate avec le même événement. pickDate vide le créneau choisi et, si une date est posée, lance le thunk fetchSlots avec { "date": "$event.value" }. Le bloc affiche alors, selon la mémoire orders, un message de chargement (status vaut "loading"), un message si la liste est vide, ou un bouton par créneau. Un clic appelle pickSlot, qui copie $s.value et $s.label ; le bouton choisi reçoit aria-pressed et la classe is-picked (voir l'exemple de join dans Les valeurs).

Payer

L'action pay est une liste de quatre étapes. Les trois premières posent les messages : submitError vidé, cartError selon que le panier est vide ou non (when, then, else), pickupError si aucun créneau n'est choisi. Aucune de ces étapes n'arrête les autres : tous les messages s'affichent ensemble.

La quatrième étape porte tout l'envoi dans un seul objet. Son when exige un panier non vide et un créneau ; validate vérifie le nom, l'e-mail et le téléphone et arrête l'objet si l'un échoue ; dispatch envoie la commande au thunk submitOrder. note passe par { "if": ["$note", "$note"] } : vide, il vaut undefined et la clé n'est pas envoyée, le JSON n'écrivant pas une valeur undefined.

Le résultat est nommé order. Si la réponse porte un providerSecret (cherché à deux endroits avec or, la réponse pouvant l'envelopper dans data), le bloc copie le panier et son total dans snapshot et snapshotTotal, transmet le secret à la mémoire payment (setProviderSecret), puis vide le panier (clearCart). La copie lit le panier du rendu où le clic est parti, donc avant qu'il soit vidé. Sinon, submitError reçoit {errSubmit} ; une erreur réseau donne un résultat undefined et passe par la même branche.

L'écran de paiement

Le passage au paiement n'est pas un atome du bloc : c'est $store.paymentReducer.providerSecret. Les étapes du formulaire portent "unless": "$store.paymentReducer.providerSecret", le nœud paying porte le when contraire et embarque le bloc paymentStep par un nœud fragment. Le récapitulatif lit le panier tant que le paiement n'a pas commencé, puis snapshot, et le total suit la même règle avec un if :

Limites et pièges

Ce que le DSL ne fait pas, et les erreurs qui ne produisent aucun message.

Pas de paramètre de route dans le scope

Le scope ne contient ni les segments dynamiques de la route (devis/[id]), ni la query string. Un hook de quelques lignes, web/configurations/logic/<id>/index.js, les expose : la page lui passe args, qui porte locale, pathname et un champ par segment dynamique (voir Le comportement en JavaScript). Pour la query string, le hook la lit avec useSearchParams de Next.

Pas de division ni d'arrondi

Pour calculer, derive offre add, mul et clamp : ni soustraction, ni division, ni arrondi. Une soustraction s'écrit add(a, mul(b, -1)), une division mul(a, 0.01) (l'inverse du diviseur). Le seul arrondi est amountFromCents, qui arrondit à l'unité et renvoie un texte : multipliez d'abord par 100 pour arrondir un montant à l'euro. Un configurateur calcule ainsi un prix, un acompte et un solde :

La spécificité CSS des styleJson

Le style des styleJson est compilé dans la région /* forge:nodes:start */ ... /* forge:nodes:end */ du style.css du bloc, sous un sélecteur doublé qui porte l'id du bloc et celui du nœud : [data-forge-id="orderFlow--root"][data-forge-id="orderFlow--root"], de spécificité (0,2,0). La région est ajoutée en fin de fichier, après le CSS écrit à la main. Une règle à une classe (.orderFlow-pay) perd contre elle ; une règle à deux (.orderFlow-slot.is-picked, .orderFlow-pay:hover) perd aussi, à spécificité égale, parce qu'elle vient avant.

• Une propriété qui change avec un état (survol, classe is-on, :disabled) ne doit pas être posée aussi dans le styleJson du nœud : gardez-la dans la classe, ou écrivez l'état dans les blocs hover, focus-visible ou active du styleJson. Dans la démo, le bouton de paiement n'a pas de styleJson : son fond, son survol et son état désactivé vivent ensemble dans .orderFlow-pay.
• Les blocs d'un styleJson : base, hover, focus-visible, active, before, after, hover-before, hover-after, et les seuils de largeur minimale sm (576 px), md (768 px), lg (992 px), xl (1200 px), xxl (1400 px).
• La région est réécrite par les outils qui enregistrent le bloc (Atelier, API) ; le CSS hors de la région n'est jamais touché. Un styleJson modifié à la main ne s'affiche qu'une fois la région recompilée.
• Tous les éléments d'un repeat partagent le data-forge-id du nœud : une règle les touche tous.

Autres pièges

• when sur un nœud repeat est évalué avant la liste : filtrez avec repeat.where.
• "as": "n", "index", "count", "isFirst" ou "isLast" : l'élément est écrasé par la variable d'itération.
• Un derive qui en lit un déclaré plus bas reçoit undefined, compté 0.
• Une saisie est un texte : eq compare sans conversion, passez par number.
• Une liste vide est fausse pour when, mais vraie dans not, and, or et if : testez-la avec empty.
• Un set n'est pas visible des étapes suivantes de la même chaîne.
• Une validate seule dans une étape n'arrête pas l'étape suivante.
• navigate ne préfixe pas la langue ; Link le fait.
• fetch envoie toute méthode autre que GET en POST.
• toast affiche toujours un message de niveau information.
• Un thunk absent de cases ne fait rien ; un appel répété à l'identique dans les 10 secondes qui suivent un échec est annulé.
• Un bloc embarqué ne reçoit ses propres dictionnaires que s'il figure aussi dans le structure.json de la page.