goblin-laboratory 4.5.2 → 4.6.2

package/doc/blueprints/blueprints.md

@@ -0,0 +1,125 @@
+# 📘 Blueprints – Documentation technique
+
+## 🧠 Définition
+
+Un **blueprint** est un fichier `.js` déclaratif décrivant les **métadonnées fonctionnelles, structurelles et UI** d’une entité métier du système Xcraft.
+
+Il sert de base à :
+
+- l’interface utilisateur dynamique (UI générée à partir des métadonnées),
+- les systèmes de recherche, de filtre et d’export,
+- l’internationalisation via `T(...)`,
+- l’édition low-code ou runtime,
+- et l’assistance intelligente (LLM, agents contextuels...).
+
+## 📦 Gestion
+
+Les blueprints sont :
+
+- des **fichiers `.js`** exportant un objet conforme au `BlueprintShape`,
+- **éditables dynamiquement** par un acteur de gestion de ressources Xcraft,
+- **versionnés** dans un **sous-module Git** (`share/blueprints`),
+- **validés** à l’exécution via `parse(BlueprintShape, blueprint)`.
+
+## 🧱 Structure
+
+Un blueprint contient les sections suivantes :
+
+### entity
+
+Nom logique de l’entité cible (ex : `case`, `contact`).
+
+### fields
+
+Liste des champs déclarés, avec :
+
+- `type` (`text`, `enum`, `date`, etc.)
+- `label` (clé nabu via `T(...)`)
+- options UI (`filter`, `search`, `hintText`, etc.)
+- pour les `enum`, la liste des `values` (label, icône, couleur)
+
+### references
+
+Liste des **références unitaires** vers d'autres entités, avec configuration d'affichage (`lookup`).
+
+### collections
+
+Listes d’identifiants liés à d'autres entités, aussi enrichies par `lookup`.
+
+### ui
+
+Paramètres UI globaux pour l'entité : icône, tri par défaut, label principal, etc.
+
+## 🎛️ Philosophies clés
+
+- Simplicité : uniquement des données, aucune logique métier ou interface
+- Interopérabilité : utilisables dans le backend, le CLI, l’UI, et les assistants
+- Internationalisation native : chaque `label`, `tooltip`, `hintText` est une clé traduisible
+- Dialecte clair : pas de `many-to-one`, on utilise `references` et `collections`
+
+## 🔍 Exemples d’usages
+
+| Objectif                | Utilisation dans blueprint               |
+| ----------------------- | ---------------------------------------- |
+| Générer une table       | `fields` avec `ui.list = true`           |
+| Créer un menu déroulant | `fields.kind.values`                     |
+| Filtrer les résultats   | `fields[].ui.filter = true`              |
+| Chercher par texte      | `ui.search = 'fulltext'`                 |
+| Afficher une relation   | `references.contactId.lookup.labelPaths` |
+| Export CSV              | `fields` avec `label` et `values`        |
+
+## ✅ Exemple minimal
+
+```
+const {T} = require('nabu');
+const {parse} = require('xcraft-core-stones');
+const {BlueprintShape} = require('goblin-laboratory/lib/blueprint.js');
+
+module.exports = parse(BlueprintShape, {
+  entity: 'case',
+  fields: {
+    status: {
+      type: 'enum',
+      label: T('Statut'),
+      values: {
+        open: {label: T('Ouvert'), icon: 'mdiLockOpen'},
+        closed: {label: T('Fermé'), icon: 'mdiLock'}
+      },
+      ui: {filter: true, list: true}
+    }
+  },
+  references: {
+    contactId: {
+      entity: 'contact',
+      label: T('Contact lié'),
+      lookup: {
+        labelPaths: ['firstname', 'lastname'],
+        drilldown: true
+      }
+    }
+  }
+});
+```
+
+## 🛡️ Validation
+
+Chaque blueprint doit être validé au chargement :
+
+```
+const {parse} = require('xcraft-core-stones');
+const {BlueprintShape} = require('goblin-laboratory/lib/blueprint.js');
+
+module.exports = parse(BlueprintShape, blueprint);
+```
+
+Une erreur sera levée si le format est invalide.
+
+## 📁 Emplacement
+
+Tous les blueprints sont stockés dans le dossier :
+
+```
+share/blueprints/
+```
+
+Ils peuvent être mis à jour dynamiquement, commités dans le sous-module, et chargés au runtime.

package/doc/blueprints/case.blueprint.js

@@ -0,0 +1,107 @@
+//Exemple de blueprint pour l'entité Case
+const {T} = require('nabu');
+const {parse} = require('xcraft-core-stones');
+const {BlueprintShape} = require('goblin-laboratory/lib/blueprint.js');
+
+const blueprint = {
+  entity: 'case',
+
+  fields: {
+    reference: {
+      type: 'text',
+      label: T('Référence'),
+      required: true,
+      ui: {
+        filter: true,
+        sort: true,
+        list: true,
+        search: 'fulltext',
+        hintText: T('Identifiant interne du dossier.'),
+        tooltip: T('Utilisé pour retrouver rapidement un dossier.'),
+      },
+    },
+
+    status: {
+      type: 'enum',
+      label: T('Statut'),
+      required: true,
+
+      values: {
+        open: {label: T('Ouvert'), icon: 'mdiLockOpen', color: 'green'},
+        closed: {label: T('Fermé'), icon: 'mdiLock', color: 'gray'},
+        archived: {label: T('Archivé'), icon: 'mdiArchive', color: 'brown'},
+      },
+
+      ui: {
+        filter: true,
+        sort: true,
+        list: true,
+      },
+    },
+
+    kind: {
+      type: 'enum',
+      label: T('Type de dossier'),
+      required: true,
+
+      values: {
+        issue: {label: T('Problème'), icon: 'mdiBug', color: 'red'},
+        question: {
+          label: T('Question'),
+          icon: 'mdiHelpCircleOutline',
+          color: 'blue',
+        },
+        project: {label: T('Projet'), icon: 'mdiChartGantt', color: 'indigo'},
+      },
+
+      ui: {
+        filter: true,
+        list: true,
+        hintText: T('Catégorie fonctionnelle du dossier.'),
+      },
+    },
+  },
+
+  references: {
+    contactId: {
+      entity: 'contact',
+      label: T('Contact lié'),
+      lookup: {
+        labelPaths: ['firstname', 'lastname'],
+        iconPath: 'avatar',
+        tooltipPath: 'email',
+        drilldown: true,
+      },
+    },
+
+    customerFolderId: {
+      entity: 'customer-folder',
+      label: T('Dossier client'),
+      lookup: {
+        labelPaths: ['name'],
+        iconPath: 'icon',
+        drilldown: true,
+      },
+    },
+  },
+
+  collections: {
+    followerIds: {
+      entity: 'user',
+      label: T('Suivi par'),
+      lookup: {
+        labelPaths: ['username'],
+        iconPath: 'avatar',
+      },
+    },
+  },
+
+  ui: {
+    icon: 'mdiFolder',
+    primaryLabel: 'reference',
+    secondaryLabel: ['kind', 'status'],
+    defaultSort: ['lastEventDate', 'desc'],
+  },
+};
+
+module.exports = parse(BlueprintShape, blueprint);

package/lib/blueprints/blueprint.js

@@ -0,0 +1,146 @@
+// @ts-check
+const {Elf} = require('xcraft-core-goblin');
+const {
+  string,
+  boolean,
+  option,
+  enumeration,
+  array,
+  record,
+} = require('xcraft-core-stones');
+
+/**
+ * Décrit comment représenter une entité liée dans l'UI
+ */
+class LookupShape {
+  labelPaths = array(string); // ex: ['firstname', 'lastname']
+  iconPath = option(string); // ex: 'avatar'
+  drilldown = option(boolean); // true pour lien vers la fiche
+  tooltipPath = option(string); // champ pour info-bulle
+  descriptionPath = option(string); // champ pour résumé
+}
+
+/**
+ * Champ enum (valeur, label, icône…)
+ */
+class EnumValueShape {
+  label = string; // clé i18n
+  icon = option(string);
+  color = option(string);
+}
+
+/**
+ * Hints pour aider l’UI à générer des interfaces intelligentes
+ */
+class FieldUiShape {
+  filter = option(boolean);
+  sort = option(boolean);
+  list = option(boolean);
+  search = option(enumeration('fulltext', 'exact', 'none'));
+  hintText = option(string); // clé i18n
+  tooltip = option(string); // clé i18n
+}
+
+/**
+ * Décrit un champ d'entité
+ */
+class FieldShape {
+  type = string; // 'text', 'enum', 'date', 'number', etc.
+  label = string; // clé i18n
+  required = option(boolean);
+  readonly = option(boolean);
+  hidden = option(boolean);
+  values = option(record(string, EnumValueShape)); // enum uniquement
+  ui = option(FieldUiShape);
+}
+
+/**
+ * Pointeur vers une autre entité (ex: contactId)
+ */
+class ReferenceShape {
+  entity = string; // cible : 'contact'
+  label = option(string); // clé i18n
+  lookup = option(LookupShape); // représentation dans l’UI
+}
+
+/**
+ * Collection de pointeurs (ex: contactIds)
+ */
+class CollectionShape {
+  entity = string;
+  label = option(string);
+  lookup = option(LookupShape);
+}
+
+/**
+ * Configuration UI globale de l’entité
+ */
+class UiConfigShape {
+  icon = option(string); // ex: 'mdiFolder'
+  primaryLabel = option(string); // champ principal
+  secondaryLabel = option(array(string)); // champs secondaires
+  defaultSort = option(array(string)); // ex: ['createdAt', 'desc']
+}
+
+/**
+ * Blueprint final pour une entité
+ */
+class BlueprintShape {
+  id = string;
+  entity = string;
+  fields = record(string, FieldShape);
+  references = option(record(string, ReferenceShape));
+  collections = option(record(string, CollectionShape));
+  ui = option(UiConfigShape);
+}
+
+class BlueprintState extends Elf.Sculpt(BlueprintShape) {}
+
+class BlueprintLogic extends Elf.Archetype {
+  static db = 'blueprints';
+
+  state = new BlueprintState({
+    id: undefined,
+    entity: undefined,
+    fields: {},
+    references: undefined,
+    collections: undefined,
+    ui: undefined,
+    meta: {status: 'published'},
+  });
+
+  create(id) {
+    const {state} = this;
+    state.id = id;
+  }
+
+  change(path, newValue) {
+    const {state} = this;
+    state._state.set(path, newValue);
+  }
+}
+
+class Blueprint extends Elf {
+  logic = Elf.getLogic(BlueprintLogic);
+  state = new BlueprintState();
+
+  async create(id, desktopId) {
+    this.logic.create(id);
+    await this.persist();
+    return this;
+  }
+
+  async change(path, newValue) {
+    this.logic.change(path, newValue);
+    await this.persist();
+  }
+
+  delete() {}
+}
+
+module.exports = {
+  BlueprintShape,
+  BlueprintState,
+  Blueprint,
+  BlueprintLogic,
+};

package/lib/blueprints/blueprints.js

@@ -0,0 +1,34 @@
+// @ts-check
+const {Elf} = require('xcraft-core-goblin');
+const {string} = require('xcraft-core-stones');
+const {BlueprintLogic, BlueprintShape, Blueprint} = require('./blueprint.js');
+
+class BlueprintsShape {
+  id = string;
+}
+
+class BlueprintsState extends Elf.Sculpt(BlueprintsShape) {}
+
+class BlueprintsLogic extends Elf.Spirit {
+  state = new BlueprintsState({id: 'blueprints'});
+}
+
+class Blueprints extends Elf.Alone {
+  logic = Elf.getLogic(BlueprintsLogic);
+  state = new BlueprintsState();
+
+  async loadAll(desktopId) {
+    const reader = await this.cryo.reader(BlueprintLogic.db);
+    const blueprintIds = reader
+      .queryArchetype('blueprint', BlueprintShape)
+      .field('id')
+      .all();
+
+    //Mount all blueprint in the desktop session
+    await Promise.all(
+      blueprintIds.map((id) => new Blueprint(this).create(id, desktopId))
+    );
+  }
+}
+
+module.exports = {Blueprints, BlueprintsLogic};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goblin-laboratory",
-  "version": "4.5.2",
+  "version": "4.6.2",
   "description": "Laboratory",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -17,7 +17,8 @@
     "goblin-theme": "^2.0.0",
     "xcraft-core-goblin": "^5.0.0",
     "xcraft-core-probe": "^2.0.0",
-    "xcraft-core-transport": "^4.0.0"
+    "xcraft-core-transport": "^4.0.0",
+    "xcraft-core-stones": "^0.4.16"
   },
   "devDependencies": {
     "aphrodite": "^2.2.2",