Aller au contenu principal
DataFlow Animator

Installation

Choisissez votre framework ci-dessous. Les quatre chemins montent le même moteur, le même rendu DOM et la même feuille de style — tout vient de @dataflow-animator/core, et chaque liaison n'est qu'une fine couche au-dessus de son appel à mountPlayer.

La feuille de style n'est pas optionnelle

Aucune liaison n'embarque de CSS : vous importez toujours @dataflow-animator/core/styles.css, exactement une fois, n'importe où dans votre application. Sans elle, le balisage se monte et se mesure, mais rien n'a de taille, de couleur ni de transition — vous obtenez une boîte vide silencieuse.

Installer et utiliser​

npm install @dataflow-animator/react @dataflow-animator/core

react et react-dom (≥ 18) sont attendus en peerDependencies. Le cœur arrive tout seul, en dépendance ; installez-le explicitement quand même, puisque vous importez sa feuille de style par son nom.

import { DataFlowPlayer } from '@dataflow-animator/react';
import '@dataflow-animator/core/styles.css';

const spec = {
  direction: 'left-to-right',
  nodes: [
    { id: 'browser', type: 'laptop', text: 'Navigateur', lane: 1 },
    { id: 'api', type: 'server', text: 'API', lane: 2 },
  ],
  packets: [
    {
      id: 'req',
      kind: 'http_packet',
      packet_content: { header: 'GET /users' },
    },
  ],
  timeline: [{ type: 'move', object: 'req', from: 'browser', to: 'api' }],
};

export default function Example() {
  return <DataFlowPlayer spec={spec} />;
}
Vue, Svelte, Astro, Rails, Django…

Tout ce qui rend une balise HTML peut utiliser l'élément personnalisé — c'est tout son intérêt. Voir Paquets et liaisons pour la comparaison complète des quatre surfaces.

Dans Docusaurus​

Importez le CSS une seule fois dans src/css/custom.css puis utilisez le composant dans n'importe quel fichier MDX :

src/css/custom.css
@import '@dataflow-animator/core/styles.css';
docs/mon-article.mdx
import { DataFlowPlayer } from '@dataflow-animator/react';

<DataFlowPlayer spec={spec} mode="auto" />

Le thème auto (défaut) suit prefers-color-scheme ET un ancêtre [data-theme] (convention Docusaurus), donc le composant se synchronise automatiquement avec le bouton de thème de l'hôte.

Dans Next.js (App Router)​

Le composant utilise useState/useEffect : marquez le fichier appelant comme client component.

app/exemple/page.tsx
'use client';

import { DataFlowPlayer } from '@dataflow-animator/react';
import '@dataflow-animator/core/styles.css';

export default function Page() {
  return <DataFlowPlayer spec={spec} />;
}

Depuis un CDN, sans étape de build​

Il n'existe volontairement aucun bundle autonome : en livrer un reviendrait à livrer une seconde copie du moteur, ce que ce découpage cherche précisément à éviter. Un CDN qui réécrit les spécificateurs de modules nus (esm.sh, jspm) se suffit à lui-même :

<link
  rel="stylesheet"
  href="https://esm.sh/@dataflow-animator/core/styles.css"
/>
<script type="module">
  import 'https://esm.sh/@dataflow-animator/element';
</script>

<dataflow-player id="player" height="420"></dataflow-player>
<script type="module">
  document.getElementById('player').spec = {
    /* … */
  };
</script>

Une import map fonctionne aussi, et garde une seule copie du cœur pour tous les modules qui la demandent — la recette est dans le README de l'élément.

Auto-complétion JSON dans VS Code​

Ajoutez cette configuration dans .vscode/settings.json pour activer l'auto-complétion et la validation inline sur tous vos fichiers *.dataflow.json :

.vscode/settings.json
{
  "json.schemas": [
    {
      "fileMatch": ["*.dataflow.json"],
      "url": "./node_modules/@dataflow-animator/core/schema.json"
    }
  ]
}

Le même chemin fonctionne avec n'importe quel validateur compatible JSON Schema draft-07 (Ajv, ajv-cli, etc.). Si vous hébergez le schéma publiquement, il peut également être référencé depuis le JSON Schema Store.

SSR et hydratation​

Le lecteur ne rend aucun balisage côté serveur, quelle que soit la liaison. Il monte un moteur de rendu DOM framework-agnostique dans un effet client : le HTML statique ne contient qu'un emplacement aux bonnes dimensions, et le diagramme apparaît à l'hydratation. Aucune divergence d'hydratation possible — il n'y a rien à faire correspondre — et importer l'un de ces paquets côté serveur reste sûr : rien ne touche au DOM au niveau module.

Ce que cela coûte : une page prérendue affiche un emplacement à la place du diagramme. En React, cet emplacement n'est pas vide — il porte un indicateur de chargement, révélé seulement si l'attente dure assez longtemps pour mériter d'être signalée (la révélation est temporisée en CSS : une hydratation rapide ne fait rien clignoter). Son texte est la clé loading de labels.

Passez fallback pour y mettre le vôtre à la place — une image d'aperçu, une légende, un squelette. Il remplace entièrement l'indicateur :

<DataFlowPlayer spec={spec} fallback={<img src="/diagram.png" alt="…" />} />

NodeView se comporte de la même façon. <dataflow-player> et <dfa-player> sont client-only au même sens : ils ne rendent rien tant qu'ils n'ont pas atteint un navigateur, donc placez une image d'aperçu ou une légende autour de la balise s'il vous faut du contenu statique.