xstate component tree

XSTATE-Component-Tree

Método de utilidade para encerrar um intérprete XState e ler meta -informações do estado para que seu Statechart possa ser usado para criar uma árvore de componentes para renderizar.

Instalação

$ > npm install xstate-component-tree

Uso

Crie um Xstate Statechart e, em seguida, instancie um intérprete xstate com ele.

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

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

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

const service = interpret ( statechart ) ;

Adicione meta objetos a cada estado que você deseja representar um componente.

 Machine ( {
    initial : "one" ,

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

Os adereços para os componentes também são suportados pela chave props .

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

Em seguida, passe a instância do intérprete e uma função de retorno de chamada para este módulo!

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

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

const service = interpret ( statechart ) ;

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

O segundo argumento para a função será chamado sempre que a máquina transita. Ele passará ao retorno de chamada um novo objeto que representa todas as opiniões definidas nos estados atualmente ativos, todos corretamente aninhados para corresponder à estrutura do StatChart. Cada elemento na resposta também conterá um valor path correspondente ao estado específico que o objeto representa.

 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: []
     *     }]
     * }]
     * 
     */ 
} ) ;

Essa estrutura de dados também pode conter componentes de qualquer StatCharts Child que você criou usando invoke , eles serão percorridos e monitorados corretamente para transições e aparecerão em sua posição esperada dentro da hierarquia. Isso permite compor um StatChart maior de vários menores e ainda assim, todos contribuem com componentes para o aplicativo.

Uso avançado

Você pode carregar dinamicamente componentes ou adereços usando qualquer funcionalidade que desejar através da tecla load . Para carregar os componentes, retorne de maneira assíncrona uma promessa ou use async / await .

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

Props dinâmicos também são suportados. Para retornar os adereços, retorne uma matriz da load onde o primeiro valor é o componente e o segundo é o adesivo para o componente. Ambos os valores suportam uma promessa retornada.

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

A função load será passada os parâmetros de context e event do XSTATE.

O ajudante component

xstate-component-tree/component possui uma exportação nomeada chamada component , que é uma pequena função para abstrair a atribuição fora do objeto meta em cada nó de estado que precisa de um componente. É um invólucro de conveniência que torna a escrita com xstate-component-tree um pouco mais limpo.

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

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

A configuração de adereços para o componente é tratada passando um objeto com teclas component e props .

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

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

A chave de component e props podem ser uma função, eles serão passados o mesmo context e event args que normalmente são passados para load() métodos.

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 e instância de um intérprete xstate
• callback , uma função que será executada cada vez que uma nova árvore de componentes está pronta
• options , um objeto opcional que contém valores de configuração para a biblioteca.

As funções callback recebe dois argumentos, a primeira é a sua árvore de componentes e adereços montados. O segundo é um objeto com algumas informações úteis sobre ele:

• .state , o objeto State XState retornado para a máquina raiz
• .broadcast() , uma versão ligada da API .broadcast() documentada abaixo
• .can() , uma versão ligada da API .can() documentada abaixo
• .hasTag() , uma versão ligada da API .hasTag() documentada abaixo
• .matches() , uma versão ligada da API .matches() documentada abaixo

options

• cache (padrão true ), um booleano que determina se o valor das funções load() deve ou não ser armazenado em cache. Isso pode ser superestimado definindo meta.cache em qualquer estado da árvore onde o cache precisa ser desativado.

• stable (padrão: false ), diz à biblioteca para classificar os estados em ordem alfabética antes de passear com eles em cada camada para ajudar a garantir que a saída do componente seja mais consistente entre as transições de estado.

• verbose (padrão: false ), registra informações sobre os trabalhos internos e decisões.

Métodos de instância ComponentTree

.broadcast(eventName | eventObject, payload)

Chama o método xstate .send() em todos os intérpretes em execução na hierarquia. Isso é especialmente útil para evitar o uso da opção autoforward em todas as suas máquinas infantis invocadas.

• eventName é um evento de string a ser enviado
• eventObject é um objeto com uma propriedade de type do nome do evento, juntamente com outros campos opcionais
• payload é um objeto de campos opcionais a serem adicionados ao objeto de evento

.can(eventName | eventObject)

Chama o método xstate .can() em todos os intérpretes em execução na hierarquia.

• eventName é um evento de string a ser enviado
• eventObject é um objeto com uma propriedade de type do nome do evento, juntamente com outros campos opcionais

.hasTag(tag)

• tag é uma string, que pode ser definida nos estados usando a propriedade tags

Chama o método XSTATE .hasTag() contra todas as máquinas em execução e retorna o resultado, parando na primeira partida de sucesso.

.matches(stateName)

• stateName é um valor de estado completo ou parcial especificado como uma string

Chama o método xstate .matches() contra todas as máquinas em execução e retorna o resultado, parando na primeira partida de sucesso.

component() ajudante

O auxiliar component retorna um nó xstate como um objeto literal, é apenas um método de conveniência para os autores do Statechart.

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

• Component é um componente ou uma função de seta que será executada. Ele suporta funções que retornam um componente ou uma Promise .
• node é um nó xstate válido, o meta objeto será criado e misturado pelo component() .

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

• component é um componente bruto ou uma função de seta que será executada. Ele suporta retornar um valor ou uma Promise .
• props são um objeto de adereços ou uma função que será executada. Ele suporta a função retornando um valor ou uma Promise .

Renderizando componentes

Depois de ter a árvore dos componentes, como você a montou em sua camada de visualização depende inteiramente de você! Aqui está um breve exemplo esbelto.

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

< script >
export let components ;
</ script >