react-decision-tree-flow
v2.1.0
Published
This is a library to create declarative wizards in react.js and react-native.
Downloads
2,044
Readme
react-decision-tree-flow
This is a library to create declarative wizards in react.js and react-native.
A basic example of a full Wizard looks like this:
export const BasicTree = () => {
const tree = {
step1: ['step2'],
step2: ['step3', 'error'],
step3: [],
error: ['step2'],
};
return (
<Wizard tree={tree} first="step1">
<Step name="step1">
<div>
I am step 1
<br />
<Controls>
{({ destinations: { step2 } }) => (
<button onClick={step2}>Go to Step 2</button>
)}
</Controls>
</div>
</Step>
<Step name="step2">
<div>
I am step 2
<br />
<Controls>
{({ destinations: { step3, error } }) => (
<div>
<button onClick={error}>Go to error</button>
<button onClick={step3}>Go to Step 3</button>
</div>
)}
</Controls>
</div>
</Step>
<Step name="step3">
<div>I am step 3. No steps after me!</div>
</Step>
<Step name="error">
<div>
I am error
<br />
<Controls>
{({ back }) => <button onClick={back}>Go back to Step 2</button>}
</Controls>
</div>
</Step>
</Wizard>
);
};
Wizard
The wizard component takes in two props as inputs, a tree and the first step of the wizard. The first step is the initial state of the wizard.
const tree = {
step1: ['step2'],
step2: ['step2', 'error'],
step3: [],
error: [],
};
const MyWizard = ({ children }) => {
return (
<Wizard tree={tree} first="step1">
{children}
</Wizard>
);
};
Defining a tree
Trees are defined using JavaScript objects such as the following
const tree = {
step1: ['step2'],
step2: ['step3', 'error'],
step3: [],
error: [],
};
Each step is a key. The value for each of those keys are the possible destinations for the objects in the tree. In the above example, step1
for example can go only to step2
, and step2
may to to step3
or the error
step. An empty array such as that in step3
and error
signifies that the Wizard has no possible destinations.
If using TypeScript, I highly suggest using const assertions to allow for hinting of destinations. This may be done by adding as const
to your tree object as such.
const tree = {
step1: ['step2'],
step2: [],
} as const;
Steps
Inside of a Wizard, one should create Steps
. Steps do not have to be displayed linearly. Only one step may be shown at one. If multiple steps in a Wizard have the same name, they may both be shown.
Typically, steps are used like below:
const tree = {
step1: ['step2'],
step2: [],
};
const MyWizard = () => {
return (
<Wizard tree={tree} first="step1">
<Step name="step1">
<span> Hello From Step 1</span>
</Step>
<Step name="step2">
<span> Hello From Step 2</span>
</Step>
</Wizard>
);
};
Controls
Controls are what actually drive the Wizard. They may be surfaced via a render prop or hook.
// Render Prop
<Wizard>
...
<Controls>
{({ step, tree, destinations: { step2 }, data, back }) => (
<>
{data && <p>{data}</p>}
<button onClick={step2}>Go to Step 2</button>
</>
)}
</Controls>
...
</Wizard>;
// Hook
const { step, tree, destinations, data, back } = useControls();
When using the hook in typescript, you may pass a typeof tree
in as a generic for useControl()
to allow for hinting under destinations as such.
const myTree = {
step1: ['step2'],
step2: [],
} as const;
...
const { step, tree, destinations } = useControls<typeof myTree>();
// destinations.step1 and destinations.step2 will be hinted!
The hook and render props deliver 3 things in the return, the current step
that the wizard is at, the tree
that the wizard is using, and finally the destinations
for the wizard.
The only rule surrounding the Controls
component and it's hook is that it has the Wizard
as a descendant. It may go under a Step
or just the Wizard
in general.
Data may also be passed from step to step using the functions in destination
that data is surfaced here using the data
prop. If data is falsey, it will be undefined.
The back function allows for you to step back in the tree. It will bring the user back to the previously visited step and data
will return to what it was previously as well. One may pass data into back
as a parameter to replace the data that was in there previously with something new if desired.
destinations
aka Moving the Wizard.
Inside of the destinations object, you will find keys that correspond to where the wizard can go. The values of those keys are functions that change the state of the wizard. Consider the following example:
const tree = {
step1: ['step2', 'step3'],
step2: ['step3'],
step3: [],
};
const MyWizard = () => {
return (
<Wizard tree={tree} first="step1">
<Step name="step1">
<span> Hello From Step 1</span>
</Step>
<Step name="step2">
<span> Hello From Step 2</span>
</Step>
<Step name="step3">
<span> Hello From Step 3. The end!</span>
</Step>
<Controls>
{({ step, destinations }) => {
// At step === step1, destinations will contain { step2: () => void, step3: () => void }
// At step === step2, destination will only contain { step3: () => void }
// at step === step3, destination will be an empty object.
Object.entries(destinations).map(([stepName, goToStep]) => {
return (
<button key="stepName" onClick={goToStep}>
Go to {stepName}
</button>
);
});
}}
</Controls>
</Wizard>
);
};
Passing data from step to step.
Data may also be passed from step to step using the destination functions. For example:
const tree = {
step1: ['step2'],
step2: ['step1'],
};
const MyWizard = () => {
return (
<Wizard tree={tree} first="step1" initialData="Hello There">
<Step name="step1">
<span> Hello From Step 1</span>
<Controls>
{({ destinations: { step2 }, data }) => {
// On first render, data will be "Hello There"
// All subsequent will be "Kenobi"
return (
<>
<div>{data}</div>
<button onClick={step2('General')}> Go to step 2</button>
</>
);
}}
</Controls>
</Step>
<Step name="step2">
<span> Hello From Step 2</span>
<Controls>
{({ destinations: { step1 }, data }) => {
// Data will always be "General"
return (
<>
<div>{data}</div>
<button onClick={step1('Kenobi')}> Go to step 1</button>
</>
);
}}
</Controls>
</Step>
</Wizard>
);
};
Recipes
Effects/Middleware
One may want to put an effect onto the state of a wizard changing. Previously, this library had a middleware function. That has been removed in favor of using useEffect
. Consider the following example:
const tree = {
step1: ['step2', 'step3'],
step2: ['step3'],
step3: [],
} as const;
const WizardInternals = () => {
const { step, destinations } = useControls<typeof tree>();
React.useEffect( () => {
console.log(`I can do things with ${step}`)
}, [step])
return (
<>
<Step name="step1">
<span> Hello From Step 1</span>
</Step>
<Step name="step2">
<span> Hello From Step 2</span>
</Step>
<Step name="step3">
<span> Hello From Step 3. The end!</span>
</Step>
{
Object.entries(destinations).map(([stepName, goToStep]) => {
return (
<button key="stepName" onClick={goToStep}>
Go to {stepName}
</button>
);
});
}
</>
);
};
const MyWizard = () => {
return (
<Wizard tree={tree} first="step1">
<WizardInternals />
</Wizard>
);
};