Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/KadoBOT/react-gizmo
🦎 React Gizmo - UI Finite State Machine for React
https://github.com/KadoBOT/react-gizmo
flow react state-machine transition xstate
Last synced: about 1 month ago
JSON representation
🦎 React Gizmo - UI Finite State Machine for React
- Host: GitHub
- URL: https://github.com/KadoBOT/react-gizmo
- Owner: KadoBOT
- Archived: true
- Created: 2018-02-03T09:38:18.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2018-07-17T00:53:54.000Z (almost 6 years ago)
- Last Synced: 2024-04-14T05:33:57.564Z (3 months ago)
- Topics: flow, react, state-machine, transition, xstate
- Language: JavaScript
- Homepage:
- Size: 168 KB
- Stars: 39
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Lists
- awesome-react-render-props - react-gizmo
- awesome-react-render-props - react-gizmo
README
# React Gizmo
UI Finite State Machine for React
#### React Gizmo is a cute State Machine that doesn't become a monster if you throw water on it
# Quick Start
## Installation
```sh
yarn add react-gizmo
```
## Usage
### PS: `react-gizmo` uses new React Context API. React 16.3 is needed for this library to work.
```js
import { Machine, State } from "react-gizmo";
const state = {
initialState: { text: "Next" },
flow: {
initial: "start",
states: {
start: { on: { NEXT: "end" } },
end: { on: { PREV: "start" } }
}
}
};
const MachineApp = () => (
);
ReactDOM.render(, document.getElementById("root"));
```
App.js
```js
class App extends Component {
render() {
return (
);
}
}
```
ButtonStart.js
```js
class ButtonNext extends Component {
handleOnClick = () => {
this.props.transition("NEXT", {
off: "start",
setState: { text: "Prev" }
});
};
render() {
return {this.props.text};
}
}
```
ButtonPrev.js
```js
class ButtonPrev extends Component {
handleOnClick = () => {
this.props.transition("PREV", {
off: "end",
setState: { text: "Next" }
});
};
render() {
return {props.text};
}
}
```
# API
## <Machine />
The <Machine /> wraps your App and is responsible for passing down the props to the <State />. The <Machine /> should have only one children, similar to `react-router`. The `initialState` and `flow` are passed to the machine through the `state` prop.
| Prop | Type | Description |
| ----- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| graph | bool | Display realtime statechart visualization |
| log | bool | If true logs state transitions |
| state | object | The object containing the state machine and initial State: { initialState: any, flow: [statechart](http://davidkpiano.github.io/xstate/docs/#/) } |
## <State />
The <State /> represents the individual state of your flow. `on` prop is what glues the state to a specific flow state, and the `children` prop returns a function with the machine props. It's recommended to use class based component for the `children` of the State so it can be referenced by the Machine.
```js
...
states: {
start: { on: { NEXT: 'end' }},
end: { on: { PREV: 'start' }}
}
...
```
| Prop | Type | Description |
| ---- | ------ | ---------------------------------------------------------------------------------- |
| on | string | Component that will be turned 'on' when flow transitions to a state with same name |
### props.transition(state[,options])
As the name suggests, this function is responsible for transitioning your app from one state to another. The first argument is the value of the state to be transitioned, and the second argument can receive a bunch of options. Like `off` to hide other non-actives <State /> components, `setState` to update your `state`/`initialState`, `draftState` which temporarily stores your changes until it's `publish`ed and `condition` where you can pass [xState Guards](http://davidkpiano.github.io/xstate/docs/#/guides/guards)
| Option | Type | Description |
| ---------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| off | oneOfType(string, arrayOf(string)) | Component(s) that will be turned 'off' when transition is called |
| setState | object | Mutates `initialState` keys with passed values |
| draftState | object | Like `setState`, but changes take effect only after being published. Newer `draftState`s will replace unpublished ones. |
| condition | any | Check xState Contitional Transitions ([Guards](http://davidkpiano.github.io/xstate/docs/#/guides/guards)) |
```js
props.transition("NEXT", {
off: "end",
setState: {
text: "Will be updated"
},
draftState: {
text: "Will update again, but only after publish"
},
condition: { shouldTransition: this.text.length < 99 }
});
```
### props.publish()
Publishes unpublished state aka. `draftState`. Draft is merged into State and then draft is cleaned. This is usefull when you are not sure if you want to update your state, I.E if a user clicks a cancel button during an API request.
```js
props.transition("NEXT", { draftState: { text: "Hello World" } });
console.log(this.props.text); // ''
props.publish();
console.log(this.props.text); // 'Hello World'
```
### props[state]
Your initialState/state, can be accessed directly via `props.YOUR_STATE_KEY`.
```js
console.log(this.props.text); // Hello
```
# Todo
* [ ] Connect state to Redux DevTools
* [ ] Examples
* [ ] Better integration with other State Managers like Redux and Mobx ie.
* [ ] Tests
# Thanks
[David](https://twitter.com/DavidKPiano) the creator of [xstate](https://github.com/davidkpiano/xstate) who made this library possible and [Michele](https://twitter.com/MicheleBertoli) for inspiring me with [react-automata](https://github.com/MicheleBertoli/react-automata). Even if you like `react-gizmo` I recommend you to give them a try.
Also, a big thanks to [Ryan Florence](https://twitter.com/ryanflorence) for giving a great talk about State Machine.