react-finite-state-machine

React Finite State Machine

Documentation in Russian

React component that implements the logic of the finite-state machine. Allows describing the component's state and the logic behind interstate transitions, transferring useful data between stages.

Prop Types

FSM Component Props

Property	Type	Required?	Description
meta	Meta	✓	Metdata. Description of stages.
onFinish	OnFinish		Hook activated after the transition to the final stage, finish() method call in the component.
beforeTransition	BeforeTransition		Hook activated before the transition to the preset stage. It's possible to interrupt the transition to the preset stage by returning false or Promise.
afterTransition	AfterTransition		Hook activated after the transition to the preset stage.
Layout	React.ReactType		General layout for all nodes of a finite state machine that receives information about the current step and children for rendering
commonProps	any		General parameters that will be sent to each node component of a finite state machine

type StageName = string | number;

/**
 * History of interstage transitions
 */
interface IHistory {
	/** Number of records in history */
	recordsCount: number;

	/** Link to the first record's object in history */
	first: IStage | null;

	/** Link to the last record's object in history */
	last: IStage | null;

	/**
	 * Method of adding a new record to history
	 * @param {StageName} stageName Stage name
	 * @param {any} payload
	 * @returns {void}
	 */
	add: (stageName: StageName, payload: any) => void;
}

type Meta<Stage extends StageName = string> = {
	/** List of stages and corresponding components ('name-component' pair) */
	stages: {
		[name in Stage]: React.ElementType<StageComponentProps>;
	};

	/** Initial stage */
	initialStage: Stage;

	/** Final stage */
	finalStage: Stage;
};

type OnFinish: (transitionsHistory: IHistory) => void;

type BeforeTransition = (currentStage: StageName, nextStage: StageName, payload?: any) => boolean;

type AfterTransition = (currentStage: StageName, prevStage: StageName, payload?: any) => void;

type CommonProps = any;

type Layout = React.ElementType<LayoutComponentProps>;

Stage Component Props

Property	Type	Description
transition	Transition	Method of transition to the present stage. Can accept useful data for transferring to the next stage.
toPrevious	ToPrevious	Method of returning to the preceding stage. Can accept useful data for transferring to the previous stage.
finish	() => void	Calls onFinish hook.
payload	IncomingPayload	Data transferred from the preceding stage.
commonProps	any	General parameters that will be sent to each node component of a finite state machine

type IncomingPayload = {} | void;

type OutGoingPayload = {} | void;

type ToPrevPayload = OutGoingPayload;

type Transition = (stageName: StageName, payload?: OutGoingPayload) => Promise<void>;

type ToPrevious = (payload?: ToPrevPayload) => Promise<void>;

type CommonProps = any;

Examples

import React from 'react';
import ReactDOM from 'react-dom';
import {FSM} from 'react-fsm';

const commonProps = {
	key: 'value'
};

const Layout = ({children, currentStage, currentStagePayload}) => (
	<div>
		{children}
	</div>
);

const Stage = {
	Stage1: 'Stage1',
	Stage2: 'Stage2',
	Stage3: 'Stage3'
};

const formsMeta = {
	stages: {
		[Stage.Stage1]: ({transition}) => (
			<div onClick={() => transition(Stage.Stage2)}>
				Stage 1
			</div>
		),
		[Stage.Stage2]: ({transition}) => (
			<div onClick={() => transition(Stage.Stage3)}>
				Stage 2
			</div>
		),
		[Stage.Stage3]: ({finish}) => (
			<div onClick={() => finish()}>
				Stage 3
			</div>
		)
	},
	initialStage: Stage.Stage1,
	finalStage: Stage.Stage3
};

const Form = () => (
	<FSM
		meta={formsMeta}
		afterTransition={(currentStage, prevStage, payload) => {
			console.log(
				`We've made a transition to the stage ${currentStage}`,
				`From stage ${prevStage}`,
				`Received payload: ${payload}`
			);
		}}
		beforeTransition={(currentStage, nextStage, payload) => {
			console.log(
				`Try to make a transition to the stage ${nextStage}`,
				`From stage ${prevStage}`,
				`With payload: ${payload}`
			);

			return !!payload.hasCats;
		}}
		onFinish={(transitionsHistory) => {
			console.log(`Finish. History: ${transitionsHistory}`);
		}}
		commonProps={commonProps}
		Layout={Layout}
	/>
);

ReactDOM.render(
  <Form />,
  document.getElementById('example')
);