Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/francisrstokes/react-machinery
🔥 React Machinery provides a simple to use, component based approach to state machines in react.
https://github.com/francisrstokes/react-machinery
javascript react state state-machine
Last synced: 14 days ago
JSON representation
🔥 React Machinery provides a simple to use, component based approach to state machines in react.
- Host: GitHub
- URL: https://github.com/francisrstokes/react-machinery
- Owner: francisrstokes
- License: mit
- Created: 2018-06-30T21:31:24.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-08T17:18:13.000Z (almost 2 years ago)
- Last Synced: 2024-08-09T09:30:07.151Z (3 months ago)
- Topics: javascript, react, state, state-machine
- Language: JavaScript
- Size: 1.84 MB
- Stars: 108
- Watchers: 8
- Forks: 5
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# React Machinery
[]()
[]()
[]()
⚙️ State Machine Modelling for React
- [Description](#description)
- [Examples](#examples)
- [Installation](#installation)
- [API](#api)
- [StateMachine](#statemachine)
- [getCurrentState](#getcurrentstate)
- [setNewState](#setnewstate)
- [states](#states)
- [data](#data)
## Description
🔥 `React Machinery` provides a simple to use, component based approach to state machines in react.
Describe your states, transitions, and which component each renders, and plug it into the `StateMachine` component. It accepts two extra functions; one for getting the current state name and one for setting it. This allows your app to flexibly use and swap out different ways of storing data - be it in component state, redux, mobx, whatever.
### Examples
Examples of how the following state diagram can be implemented in both vanilla react and using redux can be found in the examples folder.
- [Example using react](examples/1.Normal-Component-State.js)
- [Example using redux](examples/2.With-Redux.js)
## Installation
```bash
# with yarn
yarn add react-machinery
# or with npm
npm i react-machinery
```
## API
### StateMachine
All props for the `StateMachine` component are required.
#### getCurrentState
##### function()
A function returning the current state name, stored somewhere like a react component state, or in redux.
#### setNewState
##### function(newStateName)
A function that updates the current state, stored somewhere like a react component state, or in redux.
#### states
##### Array of state definitions
A state definition is a plain javascript object with the following properties:
```javascript
{
// This name corresponds to the one coming from getCurrentState() and
// being set by setNewState()
name: 'State Name',
// Array of plain objects that describe automatic transitions
// These are evaluated after a transition and when props change
autoTransitions: [
// A transition object must contain two properties:
// test, which is a function that recieves the StateMachine data, and returns true if a state change should take place
// newState, which is the name of the state to transition to when the test function returns true
{
test: data => data === 'expected for state change',
newState: 'Name of new state'
}
],
// This is a list of states that can be transitioned to from the current state using the transitionTo
// prop passed to a state component. Trying to use transitionTo with a state not specified in this list
// will throw an error. This list, together with any 'newState's described in autoTransitions form the
// full set of valid transitions for this state.
validTransitions: [
'Name of valid state'
],
// beforeRender is an optional function that can run some code before this states component
// is rendered. For anything sufficiently complex however, it's better to use a react class
// component and take advantage of lifecycle hooks
beforeRender: (data) => {
data.startAPIRequest();
},
// One of the following two properties must be implemented:
// a render prop that recieves the 'props' object supplied to the StateMachine
// the props object will also include a 'transitionTo' function and a 'currentState' string
render: (data) => {
return
},
// Or just a regular react component
component: SomeReactComponent
}
```
#### data
##### object
An object contains data that defines all the states in the state machine. This data is supplied to the component rendered by any state, to `test` functions in autoTransitions. If a render prop is used for the state, then the props are passed as the argument, along with a `transitionTo` function and `currentState` name.
# Logo
The awesome logo was designed by @ayushs08, who graciously provided under CC BY 3.0. Many thanks!