xstate component tree

xstate-composant-arbre

Méthode d'utilité pour conclure un interprète XState et lire les méta-informations de l'état afin que votre Statechart puisse être utilisée pour créer un arbre de composants à rendre.

Installation

$ > npm install xstate-component-tree

Usage

Créez un XState Statechart, puis instanciez un interprète XState avec.

 const { Machine , interpret } = require ( "xstate" ) ;

const statechart = Machine ( {
    initial : "one" ,

    states : {
        one : { } ,
    } ,
} ) ;

const service = interpret ( statechart ) ;

Ajoutez des objets meta à chaque état que vous souhaitez représenter un composant.

 Machine ( {
    initial : "one" ,

    states : {
        one : {
            meta : {
                component : MyComponent ,
            } ,
        } ,
    } ,
} ) ;

Les accessoires pour les composants sont également pris en charge via la clé props .

    // ...
    one : {
        meta : {
            component : MyComponent ,
            props : {
                prop1 : 1
            } ,
        } ,
    } ,
    // ...

Ensuite, passez l'instance interprète et une fonction de rappel à ce module!

 const { Machine , interpret } = require ( "xstate" ) ;
const ComponentTree = require ( "xstate-component-tree" ) ;

const statechart = Machine ( {
    // ...
} ) ;

const service = interpret ( statechart ) ;

new ComponentTree ( service , ( tree ) => {
    // ...
} ) ;

Le deuxième argument de la fonction sera appelé chaque fois que la machine transitions. Il passera le rappel un nouvel objet représentant toutes les vues définies sur les états actuellement actifs, tous correctement imbriqués pour correspondre à la structure du Statechart. Chaque élément de la réponse contiendra également une valeur path correspondant à l'état spécifique que représente l'objet.

 new ComponentTree ( service , ( tree ) => {
    /**
     * 
     * tree will be something like this
     * 
     * [{
     *     path : "one",
     *     component: MyComponent,
     *     children: [],
     *     props: false,
     * }]
     * 
     * or if there are nested components
     * 
     * [{
     *     path : "one",
     *     component: MyComponent,
     *     props: false
     *     children : [{
     *         path : "one.two",
     *         component : ChildComponent,
     *         props: {
     *             one : 1
     *         },
     *         children: []
     *     }]
     * }]
     * 
     */ 
} ) ;

Cette structure de données peut également contenir des composants de tout enfant Statecharts que vous avez créé à l'aide invoke , ils seront correctement parcourus et surveillés pour les transitions et apparaîtront dans leur position attendue dans la hiérarchie. Cela vous permet de composer un plus grand statechart de plusieurs plus petits et de les avoir tous apporter des composants à l'application.

Utilisation avancée

Vous pouvez charger dynamiquement des composants ou des accessoires en utilisant toutes les fonctionnalités que vous aimez via la touche load . Pour charger les composants, renvoyez de manière asynchrone une promesse ou utilisez async / await .

 // ...
one : {
    meta : {
        load : ( ) => import ( "./my/component/from/here.js" ) ,
    } ,
} ,
// ...

Les accessoires dynamiques sont également pris en charge. Pour retourner les accessoires, renvoyez un tableau à partir de load où la première valeur est le composant et le second est les accessoires du composant. Les deux valeurs prennent en charge une promesse retournée.

 // ...
one : {
    meta : {
        load : ( context ) => [
            import ( "./my/component/from/here.js" ) , 
            {
                prop1 : context . prop1
            } ,
        ] ,
    } ,
} ,
// ...

La fonction load sera transmise le context et les paramètres event de XState.

L'assistance component

xstate-component-tree/component a une exportation nommée component , qui est une petite fonction pour abstraction de l'attribution à l'extérieur à l'objet meta dans chaque nœud d'état qui a besoin d'un composant. C'est un emballage de commodité qui rend l'écriture avec xstate-component-tree un peu plus propre.

import { component } from "xstate-component-tree/component";

// ...
- one : {
-     meta: {
-         component: OneComponent,
-     },
- },
+ one : component(OneComponent),

Le réglage des accessoires pour le composant est géré en passant un objet avec component et des clés props .

import { component } from "xstate-component-tree/component";

// ...
- one : {
-     meta: {
-        component : MyComponent,
-        props : {
-            prop1 : 1
-        },
-     },
- },
+ one : component({
+    component : OneComponent,
+    props : {
+        prop1 : 1,
+    },
+ }),

La component et la clé props peuvent être une fonction, elles seront transmises le même context et les mêmes event qui sont normalement transmis pour load() .

import { component } from "xstate-component-tree/component";

// ...
- one : {
-     meta : {
-         load : (context, event) => [
-             import("./my/component/from/here.js"),
-             {
-                 prop1 : context.prop1,
-             },
-         ],
-     },
- },
+ one : component({
+    component : () => import("./my/component/from/here.js"),
+    props : (context) => ({
+        prop1 : context.prop1,
+    }),
+ }), 

API

ComponentTree

new ComponentTree(interpreter, callback, [options])

• interpreter et instance d'un interprète XState
• callback , une fonction qui sera exécutée à chaque fois qu'un nouvel arbre de composants est prêt
• options , un objet facultatif contenant des valeurs de configuration pour la bibliothèque.

Les fonctions callback reçoivent deux arguments, le premier est votre arbre assemblé de composants et d'accessoires. Le second est un objet avec quelques informations utiles à ce sujet:

• .state , l'objet State Xstate retourné pour la machine racine
• .broadcast() , une version liée de l'API .broadcast() documentée ci-dessous
• .can() , une version liée de l'API .can() documentée ci-dessous
• .hasTag() , une version liée de l'API .hasTag() documentée ci-dessous
• .matches() , une version liée de l'API .matches() documentée ci-dessous

options

• cache (par défaut true ), un booléen déterminant si la valeur des fonctions load() doit être mise en cache ou non. Cela peut être remplacé en définissant meta.cache sur n'importe quel état de l'arbre où la mise en cache doit être désactivée.

• stable (par défaut: false ), dit à la bibliothèque de trier les états de manière alphabétique avant de les promener à chaque niveau pour aider à garantir que la sortie du composant est plus cohérente entre les transitions d'état.

• verbose (par défaut: false ), connecte les informations sur les travaux et décisions internes.

Méthodes d'instance ComponentTree

.broadcast(eventName | eventObject, payload)

Appelle la méthode XState .send() sur chaque interprète en cours d'exécution de la hiérarchie. Ceci est particulièrement utile pour éviter l'utilisation de l'option autoforward sur toutes vos machines pour enfants invoquées.

• eventName est un événement à chaîne à envoyer
• eventObject est un objet avec une propriété type du nom de l'événement, ainsi que d'autres champs facultatifs
• payload est un objet de champs facultatifs à ajouter à l'objet de l'événement

.can(eventName | eventObject)

Appelle la méthode XState .can() sur chaque interprète en cours d'exécution de la hiérarchie.

• eventName est un événement à chaîne à envoyer
• eventObject est un objet avec une propriété type du nom de l'événement, ainsi que d'autres champs facultatifs

.hasTag(tag)

• tag est une chaîne, qui peut être définie sur les états à l'aide de la propriété tags

Appelle la méthode XState .hasTag() contre toutes les machines en cours d'exécution et renvoie le résultat, en s'arrêtant au premier match réussi.

.matches(stateName)

• stateName est une valeur d'état complète ou partielle spécifiée comme une chaîne

Appelle la méthode XState .matches() contre toutes les machines en cours d'exécution et renvoie le résultat, en s'arrêtant au premier match réussi.

component()

L'assistance component renvoie un nœud xstate en tant que littéral d'objet, il s'agit uniquement d'une méthode de commodité pour les auteurs de StateChart.

component(Component | () => {}, [node])

• Component est soit un composant ou une fonction flèche qui sera exécutée. Il prend en charge les fonctions qui renvoient un composant ou une Promise .
• node est un nœud XState valide, l'objet meta sera créé et mélangé par le component() .

component({ component : Component | () => {}, props : {...} | () => {} })

• component est soit un composant brut, soit une fonction flèche qui sera exécutée. Il prend en charge le rendement d'une valeur ou d'une Promise .
• props sont soit un objet d'accessoires, soit une fonction qui sera exécutée. Il prend en charge la fonction renvoyant une valeur ou une Promise .

Composants de rendu

Une fois que vous avez l'arbre des composants, la façon dont vous avez assemblé cela dans votre calque de vue dépend entièrement de vous! Voici un bref exemple de svelte.

{#each components as { path, component, props, children } (path)}
    < svelte:component this = {component} {...props} {children} />
{/each}

< script >
export let components ;
</ script >