Éditeurs

La carte des éditeurs

Kubbler a deux familles d'éditeurs. Ceux de la bibliothèque d'un espace de travail modifient des documents réutilisables (blocs, modèles, chartes graphiques, mises en page, API), rangés dans la base de Kubbler. Ceux d'un projet modifient les fichiers du dépôt de ce projet, sous web/ (le site) et api/ (le serveur). Dans un projet, chaque enregistrement devient un commit du dépôt de dev ; seule la mise en ligne publie.

L'Atelier d'une démo de pâtisserie, plan Page : la barre, le rail à gauche, la page d'accueil en édition directe et le plateau de vue en bas.w/[wsSlug]/p/[slug]

Les adresses ci-dessous sont les chemins déclarés dans routes.json : [wsSlug] désigne l'espace de travail, [slug] le projet. Dans l'Atelier, le paramètre ?sel= dit ce qui est ouvert (voir la section suivante).

Les fichiers qu'écrit un éditeur de projet

Les chemins sont relatifs à la racine du projet. Pour un bloc, le dossier est web/configurations/components/{id}/ ou web/configurations/fragments/{id}/, selon l'endroit où il vit déjà.

Le Studio : d'une description au projet

w/[wsSlug]/studio crée un projet en sept étapes, dans cet ordre :

• L'idée : le nom du projet et sa description (« Qu'est-ce que tu vas construire ? »).
• Approfondir : Kubbler relit l'idée avant de construire et peut poser des questions, facultatives.
• Le fond : logo, coordonnées, horaires, photos, ce que vous avez déjà ; ce que Kubbler ne doit pas inventer.
• L'apparence : une charte de la bibliothèque, « Laisser Kubbler choisir », ou « Créer la tienne ».
• La forme : un modèle de départ, « Partir de zéro », « Créer le tien » (l'éditeur de modèle) ou « Importer un design ».
• Les fonctions du site : des briques déjà écrites et testées (paiement, réservation...), posées au lieu d'être générées.
• On lance ? : le texte exact avec lequel Kubbler va construire, que l'on peut compléter, puis « Créer le projet ».

Le Studio, première étape sur sept : le nom du projet et sa description, avec les repères qui se cochent à droite.w/[wsSlug]/studio

Le fond, L'apparence, La forme et Les fonctions du site se passent (« Passer »). Le projet naît en brouillon au premier « Continuer » : il apparaît dans l'onglet Brouillons de la liste des projets, avec « Reprendre » et « Abandonner », et ne remplace jamais un autre brouillon. « Créer le projet » achète les briques et prépare le plan ; le prix de la construction s'affiche sur la carte du plan, avant toute construction. Les pages de mentions légales et de confidentialité sont toujours ajoutées. L'Atelier s'ouvre dès que le projet a une première version.

L'Atelier : barre, rail et plateau

L'Atelier est la surface d'un projet où tout se lit et s'édite, à w/[wsSlug]/p/[slug]. Il a deux racines : Page, la page du site en édition directe, et Mécanismes, tout ce qui fait fonctionner le projet, de la page aux données. Ouvrir un objet depuis l'une d'elles remplace le canevas par son éditeur, sous la même barre. Tant que le projet n'a pas de première version, l'Atelier affiche « Le site se prépare », avec l'assistant du projet ouvert ; « Ouvrir l'assistant du projet » le rouvre s'il a été fermé.

La barre

Un projet n'a qu'une barre, haute de 44 px, lue de gauche à droite :

12345789101112

La barre sur un écran de 1600 px, coupée en deux pour se lire : à gauche la navigation, à droite l'environnement et l'enregistrement. Les numéros renvoient au tableau ; le fil de l'objet (6) ne paraît que sur un objet ouvert.

Sur les Mécanismes, la barre n'a ni Annuler ni Enregistrer : elle porte les pastilles des couches, la pastille des problèmes, « Exporter » et « Rafraîchir les mécanismes ».

Le rail

À gauche, le rail ouvre un volet à la fois, large de 360 px. Ses onglets forment deux groupes séparés par un filet, Structure (ce dont l'objet est fait) et Sélection (ce qui est choisi), plus des onglets utilitaires en bas. Le groupe Sélection reste éteint tant que rien n'est choisi, et sa bulle dit pourquoi (« Choisissez un bloc sur la page pour voir son style et ses réglages. »). Un onglet n'apparaît que si la surface a un volet à y mettre.

12345610

Le rail en plan Mise en page, le volet Mise en page ouvert. Les onglets absents ici (Collections, Schéma, Slots exposés, Appels API, Code, Exécuter, Assistant IA) paraissent sur les surfaces qui les portent.

Le plateau de vue

En bas du canevas, le plateau de vue porte ce qui change la façon de regarder, jamais le document : l'appareil (Ajusté, Mobile, Mobile paysage, Tablette, Portable, Bureau, Large, ou une taille libre), le zoom (loupe, pourcentage que l'on peut taper, loupe, ajuster), « Rafraîchir l'aperçu », et selon la surface les pages d'exemple ou la charte d'essai. Il se déplace par sa poignée ; un double-clic le remet en bas. Quand un bloc est choisi, sa partie gauche porte les gestes de ce bloc : Monter, Descendre, Dupliquer, l'ajout à l'assistant, et Supprimer après un filet.

Les adresses de l'Atelier

Ce qui est ouvert s'écrit dans un seul paramètre, ?sel=. Un lien copié par « Copier le lien » rouvre la même sélection.

Raccourcis

Le plan Page

Le plan Page monte la vraie page du site dans un canevas, l'« Aperçu en direct », servi par l'aperçu du projet en mode édition. Un clic choisit un nœud et ouvre l'Inspecteur ; un texte se modifie en place, dans le canevas ; un bloc se pose en le glissant depuis Ajouter. Les gestes sont rendus tout de suite dans le canevas, sans recharger l'aperçu, et gardés dans le brouillon de la page en quelques secondes.

Ce plan écrit trois fichiers de la vue ouverte : structure.json (l'arbre), style.css (les règles compilées des styleJson) et dictionaries/{locale}.json (les textes). Dans un projet, la barre n'a pas de menu des pages : une page s'ajoute dans le Plan du site, et la racine Page ne fait que choisir la page affichée. Dans l'éditeur de Modèle, le même plan porte un menu Pages : « Nouvelle page » (Nom, Adresse), Renommer, Supprimer ; l'accueil garde son adresse et ne se supprime pas.

Arborescence

L'arbre de la page : chaque section, chaque bloc posé, et l'intérieur d'un bloc construit en arbre (tree.json), qui se déplie. Chaque ligne donne le nom lisible du nœud, puis son identifiant en chasse fixe. Un clic sur une ligne choisit le nœud et le souligne dans le canevas.

Inspecteur

Un seul onglet pour la sélection : le contenu d'abord, puis le style. Le contenu montre les champs du nœud (Texte, Libellé, Titre, Sous-titre, Texte indicatif, Description, Légende), le niveau d'un titre, l'adresse d'un lien, et pour une image « Remplacer l'image » et « Texte alternatif ». « Revenir au dictionnaire » remet un texte réécrit à la valeur du dictionnaire du projet. Un texte piloté par une donnée ou calculé par le comportement ne se modifie pas ici : l'éditeur renvoie à sa source.

Un bloc choisi dans le canevas : l'Inspecteur liste ses textes, chacun avec sa clé de dictionnaire (titleA_homeHero) et sa valeur en français.w/[wsSlug]/p/[slug]?sel=ui:{id}

Le style se règle par genre d'élément (un conteneur commence par sa disposition et ses alignements), puis « Plus de réglages ». Chaque ligne propose les valeurs de la charte, en mots ou en pixels, et « Autre valeur... » pour une valeur sur mesure ; chaque champ montre en gris la valeur que l'aperçu affiche. Une liste « État » choisit Normal, Au survol, Focus clavier ou Au clic. Le pli « Avancé » porte « États du bloc », « Effacer les styles » et « Ouvrir dans le code », qui ouvre le fichier dans Code, en lecture. « Changer les couleurs de tout le site » mène à la charte graphique du projet.

Ajouter

La palette a quatre onglets et une recherche : Blocs (les blocs de Kubbler qu'un aperçu sait rendre), Éléments (texte, formulaire, média, conteneurs et grilles), Bibliothèque (les blocs de l'espace, « Cet espace » et « Publics » ; un bloc « Payant » s'achète dans la bibliothèque avant d'être posé) et Sections (des sections prêtes, rangées par catégorie). « Ajouter un conteneur » pose un conteneur. Un élément cliqué s'ajoute à la fin de la page ; glissé, il se pose à l'endroit voulu. Les blocs de la Bibliothèque et les Sections se posent par l'API du projet.

Mes blocs

La liste des blocs du projet, chacun avec « Utilisé N fois ». Un clic choisit sa première occurrence ; « Ajouter à la page » pose une nouvelle occurrence du même bloc ; « Copier pour le modifier à part » en fait une copie indépendante. Sans bloc à vous, le volet renvoie à Ajouter.

Comportement

L'onglet Comportement liste les blocs de la page qui portent un comportement ; en choisir un ouvre le volet Comportement à côté du canevas, qui se rétrécit sans être recouvert. Le volet se lit « En clair » ou « Tel qu'écrit » (Façon de lire) ; une ligne choisie s'ouvre dans l'Inspecteur, et l'onglet Code montre le JSON du comportement. Un bloc partagé est copié dans le projet à la première modification de son comportement.

Le menu du canevas

Un clic droit sur un nœud ouvre un menu adapté à son genre :

Mise en page (zones)

La mise en page est ce qui reste pareil d'une page à l'autre : en-tête, menus, pied de page. Une page ne nomme jamais sa mise en page. Elle appartient à un groupe de pages (group dans routes.json), et c'est le groupe qui porte la mise en page (pageGroups[].layout dans web/configurations.json). Un groupe dont layout vaut null affiche ses pages en plein écran.

Une mise en page vit dans web/configurations/layouts/{id}/ : options.json (les zones et la grille), style.css, et un index.js figé, le même pour toutes. Exemple réel, celle d'un site vitrine :

Modifier la mise en page dans l'Atelier

Sur le plan Page, l'interrupteur « Mise en page » de la barre fait passer le canevas sur la mise en page de la page. Les mêmes outils (Inspecteur, Ajouter, Arborescence) écrivent alors layouts/{id}/options.json et son style.css, et le rail l'annonce : « Vous modifiez la mise en page : ce changement vaut pour toutes ses pages. ». L'interrupteur est éteint quand la page n'a pas de mise en page. Le sélecteur collé à l'interrupteur choisit le groupe de pages de la page ; « La mise en page change à l'enregistrement. ».

L'interrupteur « Mise en page » allumé : la page passe en grisé, les zones portent leur nom (En-tête, Contenu de la page), « + Ligne » et « + Colonne » ajoutent une zone.

En plan Mise en page, Ajouter ne propose que les blocs de structure du site (barre de navigation, pied de page et leurs compagnons) et des conteneurs : aucun élément de texte, car la copie d'une mise en page vit dans les blocs qu'elle monte. Sur le canevas, chaque zone montre son contour et son nom ; une case vide porte « Ajouter une zone ici », les bords de la grille « + Ligne » et « + Colonne », et la zone choisie ses boutons - et + qui la réduisent ou l'agrandissent de chaque côté.

L'onglet Mise en page du rail décrit la zone choisie, en mots et jamais en CSS :

Le même volet donne la structure de l'appareil regardé (« Vous modifiez la version » Mobile, Tablette ou Ordinateur) : « Faire une version à part pour » un appareil crée une bande propre, « Revenir à la structure commune » la retire. Il liste les « Pages qui utilisent cette mise en page » et la « Bibliothèque des mises en page » : « Envoyer cette mise en page à la bibliothèque », ou « Reprendre une mise en page de la bibliothèque », qui la copie dans le projet et la donne au groupe de la page au prochain Enregistrer.

Le Plan du site

w/[wsSlug]/p/[slug]/site dessine trois colonnes : Mises en page, Groupes de pages, Pages. On glisse une page sur un groupe pour la déplacer, un groupe sur une mise en page pour lui donner cette structure ; les boutons « Groupe de pages » et « Page » en ajoutent. Un clic ouvre la page dans l'Atelier. Le plan est un document : ses changements restent en brouillon, et Enregistrer écrit routes.json, web/configurations.json et les fichiers des pages ajoutées en un seul commit.

Une mise en page de la bibliothèque

w/[wsSlug]/library/layouts/[lid] ouvre une mise en page de la bibliothèque dans le même éditeur, sur des « Pages d'exemple » au choix : Site vitrine, Tableau de bord, Blog éditorial, Page vierge.

Mécanismes

Les Mécanismes dessinent le projet entier sur une carte qui se lit de gauche à droite, de la page aux données. Chaque lien dit qui déclenche, appelle, lit ou écrit quoi. La carte ne modifie rien par elle-même : on modifie en ouvrant une carte dans son éditeur, ou en créant une collection ou une route depuis Ajouter.

123456

La carte d'une démo, de gauche à droite : page (1), comportements (2), routes (3), tâches de fond (4), collections (5), et les services Kubbler (6). La chaîne du bloc de commande est tracée en encre.w/[wsSlug]/p/[slug]?sel=map:behavior:orderFlow

Les liens

La barre et le plateau

À gauche, une pastille par couche, avec son compte : un clic masque la colonne et ses liens. À droite, la pastille des problèmes, qui dit où ils vivent : « 1 problème dans la version de travail » en Dev, « 1 problème sur le site en ligne » en Prod. Un clic liste les problèmes de la carte (liens, collections) et les surligne ; ceux d'un comportement se lisent dans son volet. Puis « Exporter » (OpenAPI 3.0, Fichier Swagger (.html), Postman), qui exporte le contrat de l'API du projet, et « Rafraîchir les mécanismes ». Le plateau porte le zoom, « Tout afficher », « Cadrer la chaîne » et la minicarte.

L'Inspecteur d'une carte

Un clic sur une carte trace son chemin, de la page aux données, et ouvre l'Inspecteur. Sa tête nomme la carte et l'action qui l'ouvre : « Ouvrir le comportement », « Ouvrir le bloc », « Ouvrir la page »... ; « Voir dans la page » mène au bloc sur sa page. Suivent les sections Liens (« Déclenché par », « Appelle », « Lu par », « Écrit par »...), Exprimé sur (les pages où le bloc s'affiche) et Chaîne, qui compte ce que la chaîne traverse (par exemple 1 bloc, 2 routes, 3 collections, 1 capacité) et porte « Cadrer la chaîne ». La fiche d'un comportement donne aussi le chemin de son tree.json, son nombre de variables d'état et d'actions déclarées.

La fiche d'une tâche de fond montre son Exécution dans l'environnement actif : Planification, Taille de lot, Tentatives max, la File d'attente, les Dernières exécutions, et l'interrupteur « Allumer ou éteindre cette tâche ».

Ouvrir, et créer

Ouvrir une carte (double-clic, Entrée, ou le bouton de la tête) remplace la carte par l'éditeur de l'objet, sous la même barre : la Page pour une page ou un bloc posé, l'éditeur de Bloc pour un comportement (son volet Comportement ouvert), l'éditeur d'API pour une route, une tâche de fond ou la Structure d'une collection, les Données pour ses lignes. Le fil d'Ariane ramène à la carte ; Échap remonte d'un cran.

Le rail des Mécanismes a trois onglets : Projet, Ajouter et Inspecteur. Ajouter propose « Nouvelle collection », « Nouvelle route » et « Importer » ; ces gestes s'appliquent tout de suite au serveur du projet (voir l'éditeur d'API).

L'éditeur de Bloc, et ce que le canevas exécute

L'éditeur de Bloc modifie un bloc construit en arbre. Dans un projet, il s'ouvre à w/[wsSlug]/p/[slug]/edit/fragment/[fid], ou dans l'Atelier depuis un comportement des Mécanismes. Dans la bibliothèque, il s'ouvre à w/[wsSlug]/library/fragments/[slug], et le comportement seul à la même adresse suivie de /behavior. Dans un projet, Enregistrer écrit le dossier du bloc (tree.json, slots.json, editor.json, style.css, dictionaries/{locale}.json) en un seul lot et un seul commit.

Barre et rail

La barre porte Interactif (un bouton qui s'enfonce), « États du bloc », « Langue » quand le document en a plusieurs, et « Charte » : la charte sous laquelle on voit le bloc, celle de la plateforme par défaut, ou la « Charte du projet ». Le plateau ajoute « Prévisualiser le thème clair » ou « ... sombre ». Le rail a Ajouter (Blocs, Éléments), Arborescence, Mes blocs, Comportement, Slots exposés, Inspecteur, Appels API, Code (« Code du bloc »), Exécuter et Assistant IA.

• Slots exposés : un texte du bloc devient un slot dès qu'il porte une clé ; le volet le renomme et donne sa valeur par langue.
• Appels API : les « Routes appelées », chacune « déclaré » ou « détecté » ; « Relier une route » en ajoute une, « Déclarer » écrit un appel détecté comme appel déclaré.
• Bloc imbriqué : un bloc placé dans celui-ci se règle ici pour cet emplacement seulement ; sa structure se modifie dans son propre éditeur. « Revenir au bloc entier » quitte l'emplacement.

Le canevas n'exécute rien

Dans la Page comme dans le Bloc, le canevas d'édition ne fait jamais tourner un comportement : styler un bouton ne doit pas lancer son appel. Un bloc relié aux données y est rendu avec ce qui se lit sans rien exécuter : ses options, l'état initial de son comportement, ses valeurs calculées pures, et un jeu de données déduit de web/configurations/stores/stores.json et des références que l'arbre lit. Une liste répétée y montre des lignes d'exemple ; un champ que l'arbre lit mais que rien ne déclare reste vide.

Une référence que l'éditeur ne résout pas ainsi s'affiche telle qu'elle est écrite. Par exemple, dans la fiche d'une session de formation, le canevas peut montrer $s.seatsLeft ou $s.location là où le site publié affichera un nombre de places et un lieu : la valeur vient des données à l'exécution. Le texte d'une telle référence ne se modifie pas dans le canevas (« Ce texte est piloté par... : modifiez-le à sa source, pas ici. »).

« États du bloc » choisit l'écran que le canevas peint parmi ceux que le comportement déclare par ses conditions when et unless (un écran de chargement, d'erreur, de liste vide...). « Le canevas peint l'état choisi ; la page publiée part toujours de Départ. »

Le mode Interactif

Pour voir le comportement tourner, le Bloc a un mode Interactif : « Le comportement du bloc tourne : les clics l'atteignent et le volet Comportement lit les vraies valeurs. ». L'onglet Exécuter liste alors chaque exécution ; un clic en marque les lignes dans le volet Comportement. Le mode se demande à chaque session et n'est jamais celui par défaut ; le désactiver revient à « Éditer le bloc : sélectionner, styler, déplacer. ».

Charte graphique

La charte graphique porte les couleurs, les typographies, le logo et les espacements. Celle d'un projet s'ouvre par le menu du projet (« Charte graphique ») ou par Paramètres, section Charte graphique (« Changer ou modifier la charte »), à w/[wsSlug]/p/[slug]/edit/brand. Celles de la bibliothèque s'ouvrent à w/[wsSlug]/library/design-system/[slug].

Enregistrer la charte d'un projet écrit deux choses, qui doivent réussir toutes les deux : la charte du projet en base, que l'éditeur relit à l'ouverture, et web/configurations/brand.identity.json, le fichier que le site lit. « Changer de charte » reprend une charte de la bibliothèque ; seul son contenu est écrit.

Deux thèmes

Un sélecteur dit quel thème on modifie, Sombre ou Clair. Le thème sombre sert de base (dark) ; le clair (light) reprend chaque couleur qu'il ne redéfinit pas. Une valeur propre au clair porte « Propre au clair » ; vue depuis le sombre, « Le clair diffère » signale qu'elle a sa propre valeur en clair. La police, les tailles, les arrondis, les espacements et la grille sont communs aux deux thèmes. « Réinitialiser » remet un réglage à sa dernière valeur enregistrée, pour le thème modifié.

Thème clair : « Propre au clair » marque une couleur que le clair redéfinit.w/[wsSlug]/p/[slug]/edit/brand

Thème sombre, la base : « Le clair diffère » signale une couleur que le clair remplace.w/[wsSlug]/p/[slug]/edit/brand

L'aperçu montre la charte sur une « Page d'exemple » qui fait voir chaque réglage, et sur « Votre site, page d'accueil » quand l'aperçu du projet a démarré.

Éditeur d'API et Données

L'éditeur d'API

Dans un projet, l'éditeur d'API s'ouvre depuis les Mécanismes sur une route, une tâche de fond ou la Structure d'une collection. Hors projet, w/[wsSlug]/apis/[schemaId] ouvre une API de la bibliothèque sur sa carte, et chaque pièce a sa propre adresse, que l'on peut partager : apis/[schemaId]/controller/{group}.{name}, apis/[schemaId]/module/{taskType}, apis/[schemaId]/collection/{name}.

Dans un projet, chaque geste s'applique tout de suite et devient un commit du dépôt de dev ; l'éditeur l'annonce en mots (« Collection ajoutée. », « Route retirée. », « Routes de la collection générées. »). Les fichiers écrits :

La collection orders dans l'éditeur d'API : ses champs avec leur type et leurs règles, puis les routes, comportements et pages qui l'utilisent.w/[wsSlug]/p/[slug]?sel=col:orders

Dans la bibliothèque, les gestes écrivent un brouillon que le serveur garde, et Enregistrer le promeut. Une API neuve s'ouvre à apis/new?draft={id} sans rien écrire ; son premier Enregistrer demande son nom et crée sa ligne. La copie d'un preset emporte ses briques : son premier Enregistrer en affiche le prix (« Enregistrer pour ... ») et les paie ; refuser le prix ou le nom n'écrit rien.

L'éditeur seul a une « Vue du plateau » (Les deux, Schéma, Routes) et son Dev / Prod : Dev, « Aperçu et bac à sable : non publié » ; Prod, « En ligne, en lecture seule ». « Importer » accepte un JSON OpenAPI 3.0, Swagger 2.0 ou Postman v2.1, au format détecté ; une collection Postman n'importe que les routes, sans schéma de base.

Le déroulé d'une route ou d'une tâche de fond ajoute les onglets Code (le handler produit) et Exécuter. Le bloc « Essayer » envoie la requête (« Envoyer ») sur les données de l'Aperçu du projet, en Dev seulement ; « Réinitialiser les données » vide ces données. Une tâche de fond se lance « Essayer à blanc », sur une base en mémoire jetable, ou par « Peupler la base ».

Données

Les Données montrent les documents réellement stockés dans une collection, dans l'environnement actif. Elles s'ouvrent depuis une collection des Mécanismes (« Voir les données », ou le segment Données du fil) ; l'onglet Collections du rail passe ensuite d'une collection à l'autre ; l'adresse est ?sel=data:col:{name} en Dev, ?sel=data.prod:col:{name} en Prod. La barre dit la source de la collection, la base lue (« Base : ... »), le nombre de lignes, et porte « Rafraîchir » et « Ajouter ». L'environnement se change dans la barre du projet, pour tout l'Atelier.

En Dev, les documents s'écrivent tout de suite, sans brouillon : un clic sur une ligne ouvre son document dans l'Inspecteur (onglets Champs et JSON, « Copier l'identifiant », « Copier le JSON », dates de création et de modification), Enregistrer l'écrit dans la base, et « Supprimer » demande confirmation (« Supprimer ce document de ... ? Action irréversible. »). « Ajouter » ouvre un Nouveau document ; il faut au moins un champ déclaré. Un champ présent en base mais absent de la structure se lit sans se modifier. Dans quatre cas, la surface est en lecture seule, le bouton Ajouter n'existe pas et une pastille dit pourquoi :

Les commandes d'une démo en Dev : la grille des documents, et la commande choisie ouverte dans l'Inspecteur (onglets Champs et JSON).w/[wsSlug]/p/[slug]?sel=data:col:orders

Dans la grille, un clic sur un en-tête trie la colonne (un champ non indexé le signale : le tri peut être lent sur une grande collection). Une colonne présente en base mais absente de la structure porte « non déclaré », un champ masqué par le serveur s'affiche « masqué », et une référence s'ouvre dans sa collection (« Ouvrir le document lié dans ... »). Le pied donne « Lignes a-b sur t » et « Par page » : 20, 50 (par défaut), 100 ou 200.

« Ajouter un filtre » pose une condition : Champ, Condition, Valeur, puis « Appliquer ». « parmi » et « hors de » prennent des valeurs séparées par des virgules. Les conditions dépendent du type du champ :

Le bouton JSON montre le filtre sous sa forme JSON Mongo, que l'on peut aussi écrire puis lancer par « Filtrer ». Seuls les opérateurs $gt $lt $gte $lte $in $nin $or $and $ne $exists sont acceptés ; un filtre qui ne se lit pas en conditions simples reste en JSON. Rien n'est lu pendant la frappe : la lecture part sur Appliquer ou Filtrer.

L'onglet Schéma décrit la collection : chaque champ avec « requis », son type (Texte, Paragraphe, Nombre, Oui ou non, Date, Liste, JSON, Identifiant, Objet) et ses règles (format, longueurs), puis « Index », « Champs non déclarés », et « Lue par » / « Écrite par », les routes qui lisent et écrivent la collection. Le schéma se modifie dans l'éditeur d'API, par le segment Structure.

Le contrat d'écriture, et Code en lecture

La Page, la Mise en page, le Bloc et le Modèle écrivent un même format, celui du design system de Kubbler. Une vue ou un arbre écrit à la main doit le suivre, sinon l'Inspecteur ne peut pas le relire comme ses propres réglages.

• Les classes du design system d'abord, par des contrôles fermés : squelette (container*, grid), placement (g-col(-bp)-*, g-start(-bp)-*), flex, gap, espacements, visibilité, échelle de texte, tons, arrondi, ombre. La classe s'écrit dans le porteur du dialecte : classname sur un nœud de vue (structure.json), props.className sur un nœud d'arbre (tree.json) ; un porteur déjà présent l'emporte. Les autres mots ({id}-*, btn*, badge*, form-control...) sont gardés tels quels.
• **styleJson, en jetons, pour ce qu'aucune classe ne dit** : couleurs hors des tons, dégradés, bordures fines, transitions, et les états hover, focus-visible, active. Une valeur sur mesure (« Autre valeur... ») retire la famille de classes qui réglait la même propriété : un seul réglage par nœud et par propriété.
• Les attributs de contexte data-surface et data-style, à la racine du nœud dans une vue, dans props dans un arbre. data-surface (1, 2 ou 3) donne le niveau de surface ; data-style (flat, outlined, elevated, soft, glass) peint la matière, et une valeur vide prend la matière choisie dans la charte.
• **Un _nid sur chaque nœud** de vue et sur chaque zone de mise en page : c'est l'adresse du nœud pour l'éditeur, marquée data-forge-id dans le canevas. Les éditeurs le posent ; rien ne le crée à la lecture.
• Un seul format de nœud : le conteneur est primitive: "wrapper" ; un nœud fragment sans id ne rend rien ; une image est un Img avec src, alt et ses dimensions dans props, et, dans une vue ou une zone, un enfant primitive: "media" qui a son propre _nid ; une vue n'a pas de components.common ; pas de props.layout, appearance, gridCol ni gridRow en ligne.
• Deux axes de bandes, jamais mêlés : l'écran (les @media de 576 à 1400 px) pour les utilitaires, les bandes de styleJson et order-* ; la grille (le .grid parent, mesuré en @container) pour g-col-{bp}-* et g-start-{bp}-*. Un md de l'un n'est pas le md de l'autre.
• **Pas de cols-N** : la grille a toujours 12 colonnes ; « 3 colonnes » s'écrit par la largeur des enfants (g-col-4 trois fois).

Un nœud d'arbre écrit par l'éditeur, tiré d'un bloc de démonstration : classes du design system dans props.className, attributs de contexte dans props, le reste en styleJson.

Un état se règle dans le même styleJson, à côté de base :

Une image dans une vue, avec son enfant media :

Code se lit, il ne s'écrit pas

L'API du projet refuse toute écriture de fichier hors du DSL (erreur codeOutsideDsl). Le DSL, ce sont les fichiers .json et .css du projet, hors package.json, package-lock.json et fichiers cachés, plus deux modules figés, acceptés seulement avec leur contenu exact : configurations/layouts/{id}/index.js (l'index d'une mise en page à zones) et configurations/views/{view}/style.js (le crochet de style d'une vue). Les contrôleurs de l'API, le JSX et la logique des composants et les dépendances s'écrivent par l'assistant du projet, derrière ses validateurs, ou par les gestes de l'éditeur d'API. Une migration de schéma ne s'écrit jamais à la main.

D'un geste à la mise en ligne

Hors projet, une modification est perdue, en brouillon ou enregistrée. En projet s'ajoute la publication, qui déploie. Rien n'est écrit chez Kubbler en dessous du brouillon : ouvrir et regarder ne coûtent rien.

L'état, à côté d'Enregistrer

Un seul indicateur dit où en est le document : « Pas encore enregistré » (un document neuf), « Copie, pas encore enregistrée », « Brouillon gardé à 14:26 », « Brouillon gardé sur cet appareil » (connexion coupée), « Enregistrement... », « Enregistré à 14:26 », et « Modifications non enregistrées » sur un écran sans brouillon. Dans l'Atelier s'ajoute l'état en ligne : « Publié », « N modifications non publiées », « Jamais publié » ou « Hors ligne ». Enregistrer est grisé tant qu'il n'y a rien à écrire (« Aucune modification à enregistrer »). Cmd/Ctrl+S fait la même chose que le bouton, avec la même garde ; dans un éditeur à rail, les champs en cours de saisie sont écrits d'abord.

Quitter, fermer l'onglet

Un travail gardé en brouillon part sans question, et un message le dit : « Brouillon gardé : il revient à la prochaine ouverture de ce document. ». La question « Modifications non enregistrées » (« Continuer l'édition », « Quitter sans enregistrer », « Enregistrer et quitter ») ne se pose que si quelque chose serait perdu : bibliothèque pleine, brouillon refusé ou trop lourd, connexion coupée sans copie locale. Dans ce seul cas, fermer ou recharger l'onglet déclenche la confirmation du navigateur. Changer de page ou de plan dans l'Atelier ne demande rien : chaque page et chaque plan garde son historique d'annulation, rendu au retour si rien n'y a touché entre-temps.

Une coupure de l'API ne démonte jamais un éditeur ouvert : un bandeau dit que la connexion est perdue, les écritures du brouillon attendent et repartent seules au retour, et les dernières secondes sont gardées dans le navigateur pour un rechargement.

Ouvrir, c'est une copie ; renommer

Dans la bibliothèque, chaque liste a les onglets Kubbler, À moi, Marketplace, Brouillons et Corbeille. Ouvrir un document de Kubbler ou du marketplace en fait une copie à vous (« Partir de ce bloc », « Partir de ce modèle »...). Ouverte sans y toucher, la copie n'existe nulle part ; modifiée, elle devient un brouillon, rangé dans l'onglet Brouillons de sa liste avec « Reprendre » et « Abandonner le brouillon » ; son premier Enregistrer demande son nom (« Copie de ... »). Un document neuf s'appelle « Sans titre ». La Corbeille garde un document 30 jours, prêt à être restauré.

Dans un éditeur, le nom fait partie du document : un clic sur le nom, dans le fil de la barre, le renomme, et ce changement est écrit par Enregistrer. Dans une liste, « Renommer » est immédiat.

En projet : un commit, puis la mise en ligne

Dans un projet, Enregistrer écrit les fichiers en un lot puis un commit dans le dépôt de dev ; rien n'est en ligne. « Abandonner le brouillon » remet la page ouverte au dernier commit, et elle seule. Hors de ce contrat : les Données s'écrivent tout de suite ; les gestes de l'API d'un projet sont appliqués et commités un par un ; Paramètres et Env enregistrent explicitement, sans brouillon, et changer d'environnement n'y jette jamais une saisie sans le dire.

Dev et Prod

Dev / Prod, au centre de la barre, vaut pour tout l'Atelier. Dev est la version de travail : l'aperçu, ses données, ce que vous modifiez. Prod est le site en ligne, en lecture : la Page montre le site publié dans un cadre « En ligne / lecture seule », les Mécanismes lisent la version en ligne, les Données de la base en ligne ne s'écrivent pas. Prod reste inerte tant que rien n'est en ligne (« Rien n'est encore en ligne : la prod apparaît au premier déploiement. »).

Publier

« Publier » est la première entrée de la flèche d'Enregistrer de l'Atelier. Après confirmation (« Mettre en ligne la version enregistrée ? Le site en ligne sera remplacé. »), il lance le même déploiement que la page Mise en ligne. Il attend tant qu'un travail n'est pas enregistré (« Enregistrez d'abord : seule la version enregistrée part en ligne. ») et renvoie à Mise en ligne la première fois, pour l'hébergement et le domaine. L'état « Publié » ou « N modifications non publiées » compare le dernier commit à celui de la version en ligne.

Ce qui part : le déploiement est construit depuis le dernier commit, jamais depuis l'arbre de travail. Un brouillon, à vous ou à un collaborateur, ne part jamais, même s'il est déjà visible dans l'aperçu. Les pages légales, les réglages de Paramètres faits en Prod et la nouvelle version d'un schéma partent avec ce déploiement (« En ligne à la prochaine mise en ligne ») ; les secrets sont lus dans les coffres au moment du déploiement.

La page Mise en ligne (w/[wsSlug]/p/[slug]/ship) suit trois étapes : Hébergement, Domaine, Déploiement. Le domaine se configure après l'hébergement, car l'adresse du site est inscrite dans le build (liens canoniques, sitemap). L'API se déploie d'abord, le site web en dépend ; « Tout déployer d'un coup » fait les deux. La page porte ensuite les Logs, l'Historique, et Arrêter, Démarrer, Redémarrer, Redéployer. Avant le déploiement, elle relève les données privées lisibles sans compte (« Une donnée privée lisible par tout le monde ») ; la mise en ligne reste possible.

La page Mise en ligne : les trois étapes, la vérification des données privées, puis le choix d'une offre d'hébergement.w/[wsSlug]/p/[slug]/ship

Env, Paramètres, Briques, Socle légal

Env (env) range les secrets dans des coffres chiffrés de bout en bout (SharedEnv), un par couche (api, web) et par environnement : le coffre dev sert l'Aperçu, le coffre prod le déploiement. « Les clés que ce projet attend » liste les noms (Serveur, Site ; obligatoire ou facultative) ; les valeurs ne se voient qu'une fois le coffre connecté. « Autoriser kubbler » laisse la plateforme déchiffrer un coffre à chaque déploiement de sa couche ; « Révoquer » retire cet accès et renouvelle la clé. Tant qu'un secret requis par une brique manque, la mise en ligne reste bloquée (« Mise en ligne bloquée : secrets requis manquants »). Les secrets n'entrent jamais dans le dépôt.

Paramètres (settings) règle, par couche (Site, Serveur) et par environnement, les réglages du projet : Général, puis « Réglages techniques » (adresses du serveur, sources autorisées CSP, accès depuis un autre site, envoi des e-mails, paiement). En Dev, ils valent pour la version de travail ; en Prod, ils partent à la prochaine mise en ligne. La section Charte graphique ouvre l'éditeur de la charte du projet. Plus bas, Briques liste les fonctions toutes faites posées dans le projet et ce que chacune a coûté ; « Ajouter une brique » la fusionne dans le projet tout de suite, sans génération.

Le Socle légal (legal) tient l'éditeur du site (saisi pour l'espace, modifiable par projet), l'activité du site, les sous-traitants détectés et les pages légales, tirées d'un corpus écrit et versionné à la main (onglets Pages, Données, Textes, Journal). Un seul Enregistrer écrit les informations puis réécrit les pages ; une information manquante y laisse « À COMPLÉTER » et la page n'est pas indexée. Les pages partent en ligne avec la mise en ligne du projet.