# Intégrer Flowora dans une application Angular

Flowora est un éditeur de graphes, pas un moteur d’exécution. La beta est sous licence MIT, avec distribution publique et canal npm `next` approuvés par le propriétaire. Tant que la publication registry n’est pas vérifiée, le tarball local reste la méthode de consommation disponible. La compatibilité vérifiée concerne Angular 22.2.4 ; les dépendances tierces conservent leurs licences propres.

## Points d’entrée

`@newvexa/flowora` expose les types JSON, le catalogue, la classe `Editor`, le document de démonstration et les fonctions de géométrie. Cette entrée ne dépend pas d’Angular, de Rete, de Workify ni d’API Node. Elle est disponible en ESM/CommonJS et peut être utilisée dans un navigateur ou un serveur pour éditer/valider les modèles.

`@newvexa/flowora/angular` expose `FloworaEditorComponent`, un composant standalone pour Angular. Le renderer et ses API DOM sont isolés dans cette entrée ESM/partial-Ivy. L’application doit compiler et linker les bibliothèques Angular ; charger directement ce bundle partiel dans un navigateur n’est pas une intégration valide.

`@newvexa/flowora/layout` expose `ElkLayoutAdapter`. Fournir `elkjs` dans l’hôte si cet adaptateur est utilisé. L’importer n’ajoute pas un moteur d’exécution. L’adaptateur calcule des positions ; le store applique ces positions séparément et son historique permet de revenir en arrière.

## Créer une instance stable

Le README fournit un composant minimal. Construire une instance d’`Editor` par document édité, pas à chaque rendu ou changement de détection Angular. Donner au conteneur une hauteur explicite.

```ts
import { Editor, createDemoDocument } from '@newvexa/flowora';
import type { EditorDocument } from '@newvexa/flowora';

const editor = new Editor(createDemoDocument(), { historyLimit: 64 });
const off = editor.subscribe(() => {
  const snapshot = editor.getSnapshot();
  console.log(snapshot.revision, snapshot.selection);
});
const document: EditorDocument = editor.getSnapshot().document;
// L'hôte conserve le document ou editor.toJSON() dans son stockage.
off();
```

L’abonnement renvoie un nettoyage ; le composant nettoie ses abonnements et observateurs lorsqu’il est détruit ou reçoit une autre instance. Le store n’installe pas de timer, transport réseau ou sauvegarde automatique.

## Catalogue de nœuds métier

Le catalogue fourni décrit des nœuds de départ, réponse, attente, email, RAG, variables, script, condition et groupe. Ce sont des presets de données et de présentation. Le texte « envoyer email » ne configure pas un serveur SMTP et le champ script n’exécute aucun code.

Passer un catalogue personnalisé via les options de `Editor`. Un `NodePreset` comprend `type`, `label`, `category`, `color`, `icon`, `inputs`, `outputs` et `defaultConfig`. Les ports portent un identifiant, un type et une règle éventuelle de cardinalité. Les identifiants doivent être uniques dans leur direction et les connexions doivent respecter les règles du store.

`addFromCatalog(type, position)` ajoute un nœud. `updateNode(id, patch)` met à jour son nom, ses dimensions, ports ou configuration. L’état et les documents exposés sont immuables : ne pas muter directement une position ou le `config` obtenu dans un snapshot. Utiliser les commandes du store pour conserver les événements, l’historique et les validations.

Le document utilise des valeurs JSON simples et finies. Il ne peut contenir ni fonction, objet de classe, référence circulaire ou secret automatiquement injecté. Conserver les références métier utiles, pas les instances Rete ou des objets Angular.

## Personnaliser le rendu Angular

Le composant accepte `nodeTemplate` et `inspectorTemplate` pour remplacer ses présentations par les templates de l’hôte. Le contexte de nœud contient `$implicit` (le nœud), `selected` et `preset`. Le contexte inspector contient `$implicit` et `update(patch)` pour écrire via le store. Les gestes et les ports du renderer doivent conserver leur zone interactive ; arrêter la propagation de `pointerdown` sur les contrôles d’un template custom qui ne doivent pas déclencher le déplacement du nœud.

Fragment d’un template applicatif, à intégrer au composant hôte :

```html
<flowora-editor [editor]="editor" [nodeTemplate]="customNode" />
<ng-template #customNode let-node let-selected="selected">
  <div class="mon-noeud" [class.actif]="selected">{{ node.name }}</div>
</ng-template>
```

Un composant Angular métier peut être placé dans ce template pour réutiliser tes formulaires ou affichages. Les détails DOM ne deviennent pas une dépendance de l’entrée portable. Les variables CSS du composant offrent une base de thème ; les valeurs utilisateur sont affichées comme du texte, pas du HTML exécuté.

## Sauvegarde et intégration aux services de l’hôte

`saveRequested` et `exportRequested` transmettent le document à l’hôte. La démonstration fournie les relie à `localStorage` et au téléchargement JSON. Ces sorties ne signifient pas qu’une sauvegarde serveur ou publication est réalisée. `documentChange` permet à l’hôte d’observer les changements persistables ; éviter d’envoyer une requête par mouvement de souris sans regroupement adapté.

`toJSON()` sérialise le modèle versionné ; `loadJSON()` valide et remplace le document de manière atomique. Les coordonnées des nœuds sont absolues dans l’espace du graphe, même pour les enfants d’un groupe. Le viewport est sauvegardé séparément dans le même document. Le renderer affiche le document actuel, pas le statut d’exécution d’un backend absent.

Une intégration à Workify ou à un autre moteur doit compiler ce document vers un modèle d’exécution indépendant. Le store d’édition peut accepter ou refuser les cycles selon ses options ; cela ne change pas les limites de ce moteur externe. Les règles métier, authentification, secrets, approbations et exécution des scripts relèvent de l’application hôte.

## Historique, groupes et layout

Les transactions `beginTransaction()`/`endTransaction()` regroupent un geste en une action annulable. `cancelTransaction()` restaure l’état avant un geste interrompu. La sélection et les déplacements de viewport ne doivent pas remplir l’historique métier par défaut. La limite de snapshots est bornée, mais leur coût dépend de la taille du document ; ce n’est pas une base durable d’audit.

`groupSelection()` crée un groupe parent ; ses enfants conservent leurs coordonnées mondiales. Déplacer un groupe déplace ses descendants. `ungroup(id)` conserve les nœuds enfants et leurs positions. La relation parent/enfant est un groupement d’éditeur, pas l’exécution d’un sous-workflow ou une portée de variables.

Le layout ELK par défaut est local et optionnel. Le fait de retourner une Promise ne garantit pas que son calcul est dans un Web Worker. Pour des graphes complexes, fournir un `LayoutAdapter` avec son propre transport worker validé dans l’application. Flowora n’affirme pas une latence UI de production pour 2 000 nœuds sans mesure adaptée.

## Références de construction

Les exigences de peer dependencies, compilation partielle et linker sont décrites dans les pages officielles Angular consultées pour cette candidate :

[1]: https://angular.dev/tools/libraries/creating-libraries "Angular — Création et consommation de bibliothèques"
[2]: https://angular.dev/tools/libraries/angular-package-format "Angular — Format ESM et compilation partielle"