();
88 |
89 | return (
90 | <>
91 |
92 | {wizard.currentStep} step
93 |
94 |
95 |
96 | Welcome {wizard.currentValues.firstName}{' '}
97 | {wizard.currentValues.lastName}!
98 |
99 |
101 |
109 |
112 |
113 |
114 | );
115 | };
116 |
117 | function App() {
118 | return (
119 |
120 |
Robo Wizard w/ React-Router
121 |
122 | initialValues={{ firstName: '', lastName: '' }}>
123 | } />
124 | } />
125 | } />
126 |
127 |
128 |
129 | )
130 | }
131 |
132 | export default App
133 |
--------------------------------------------------------------------------------
/examples/react-router/src/favicon.svg:
--------------------------------------------------------------------------------
1 |
16 |
--------------------------------------------------------------------------------
/examples/react-router/src/main.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | import ReactDOM from 'react-dom/client'
3 | import App from './App'
4 |
5 | ReactDOM.createRoot(document.getElementById('root')!).render(
6 |
7 |
8 |
9 | )
10 |
--------------------------------------------------------------------------------
/examples/react-router/src/vite-env.d.ts:
--------------------------------------------------------------------------------
1 | ///
2 |
--------------------------------------------------------------------------------
/examples/react-router/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "target": "ESNext",
4 | "useDefineForClassFields": true,
5 | "lib": ["DOM", "DOM.Iterable", "ESNext"],
6 | "allowJs": false,
7 | "skipLibCheck": true,
8 | "esModuleInterop": false,
9 | "allowSyntheticDefaultImports": true,
10 | "strict": true,
11 | "forceConsistentCasingInFileNames": true,
12 | "module": "ESNext",
13 | "moduleResolution": "Node",
14 | "resolveJsonModule": true,
15 | "isolatedModules": true,
16 | "noEmit": true,
17 | "jsx": "react-jsx"
18 | },
19 | "include": ["src"],
20 | "references": [{ "path": "./tsconfig.node.json" }]
21 | }
22 |
--------------------------------------------------------------------------------
/examples/react-router/tsconfig.node.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "composite": true,
4 | "module": "esnext",
5 | "moduleResolution": "node"
6 | },
7 | "include": ["vite.config.ts"]
8 | }
9 |
--------------------------------------------------------------------------------
/examples/react-router/vite.config.ts:
--------------------------------------------------------------------------------
1 | import { defineConfig } from 'vite'
2 | import react from '@vitejs/plugin-react'
3 |
4 | // https://vitejs.dev/config/
5 | export default defineConfig({
6 | plugins: [react()]
7 | })
8 |
--------------------------------------------------------------------------------
/examples/react/app.tsx:
--------------------------------------------------------------------------------
1 | import { createRoot } from 'react-dom/client';
2 | import { useWizard } from '@robo-wizard/react';
3 |
4 | type Values = {
5 | firstName?: string;
6 | lastName?: string;
7 | };
8 |
9 | const App: React.FC = () => {
10 | const wizard = useWizard(['first', 'second', 'third']);
11 |
12 | const onSubmit: React.FormEventHandler = event => {
13 | event.preventDefault();
14 | const values = Object.fromEntries(new FormData(event.currentTarget))
15 | wizard.goToNextStep({ values });
16 | };
17 |
18 | return (
19 |
20 |
Robo Wizard w/ React
21 |
22 |
23 | {wizard.currentStep} step
24 |
25 |
26 |
89 |
22 |
Robo Wizard w/ Svelte
23 |
24 |
25 | {wizard.currentStep} step
26 |
27 |
28 |
76 |
38 |
Robo Wizard w/ Vue
39 |
40 |
{{ wizard.currentStep }} step
41 |
42 |
76 |
{wizard.currentStep} step
48 |
67 |
68 | )
69 | }
70 | ```
71 |
72 | Go forth and make the web a bit more magical! ✨
73 |
--------------------------------------------------------------------------------
/packages/react-router/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "@robo-wizard/react-router",
3 | "version": "1.0.3",
4 | "description": "RoboWizard components and hooks for react-router",
5 | "main": "./dist/robo-wizard_react-router.umd.js",
6 | "module": "./dist/robo-wizard_react-router.es.js",
7 | "private": false,
8 | "publishConfig": {
9 | "access": "public"
10 | },
11 | "exports": {
12 | ".": {
13 | "import": "./dist/robo-wizard_react-router.es.js",
14 | "require": "./dist/robo-wizard_react-router.umd.js"
15 | }
16 | },
17 | "types": "dist/index.d.ts",
18 | "typedocMain": "src/index.ts",
19 | "sideEffects": false,
20 | "scripts": {
21 | "start": "vite build --watch",
22 | "build": "vite build",
23 | "test": "vitest",
24 | "prepare": "vite build"
25 | },
26 | "keywords": [
27 | "wizard",
28 | "workflow",
29 | "state machine",
30 | "xstate"
31 | ],
32 | "author": "HipsterBrown",
33 | "homepage": "http://robo-wizard.js.org",
34 | "license": "MIT",
35 | "repository": {
36 | "type": "git",
37 | "url": "https://github.com/HipsterBrown/robo-wizard.git",
38 | "directory": "packages/react-router"
39 | },
40 | "dependencies": {
41 | "@robo-wizard/react": "1.1.0",
42 | "robo-wizard": "1.2.0"
43 | },
44 | "devDependencies": {
45 | "@testing-library/jest-dom": "^5.16.5",
46 | "@testing-library/react": "^13.4.0",
47 | "@types/react": "^18.0.8",
48 | "@types/react-dom": "^18.0.3",
49 | "@vitejs/plugin-react": "^3.0.0",
50 | "jsdom": "^20.0.3",
51 | "react": "^18.1.0",
52 | "react-dom": "^18.1.0",
53 | "react-router": "^6.5.0",
54 | "typescript": "^4.9.4",
55 | "vite": "^4.0.2",
56 | "vite-plugin-dts": "^1.7.1",
57 | "vitest": "^0.26.1"
58 | },
59 | "peerDependencies": {
60 | "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
61 | "react-router": "^6.0.0"
62 | }
63 | }
64 |
--------------------------------------------------------------------------------
/packages/react-router/src/components/Step.tsx:
--------------------------------------------------------------------------------
1 | import { Route, RouteProps } from 'react-router'
2 | import type { StepConfig } from 'robo-wizard'
3 |
4 | /**
5 | * @param props - accept same props as the [Route component from react-router](https://reactrouter.com/docs/en/v6/api#routes-and-route), excepte for `path`, as well as [[StepConfig]] from `robo-wizard`
6 | **/
7 | export function Step({ name, ...routeProps }: Exclude & StepConfig) {
8 | return ;
9 | }
10 |
--------------------------------------------------------------------------------
/packages/react-router/src/components/index.ts:
--------------------------------------------------------------------------------
1 | export * from "./Step";
2 |
--------------------------------------------------------------------------------
/packages/react-router/src/context/index.tsx:
--------------------------------------------------------------------------------
1 | import { Children, createContext, useContext, useEffect, PropsWithChildren, ReactNode, ReactElement } from 'react';
2 | import { useNavigate, useRoutes, Navigate, useLocation, RouteObject } from 'react-router';
3 | import type { RoboWizard, BaseValues, StepConfig } from 'robo-wizard'
4 | import { useWizard } from '@robo-wizard/react'
5 | import { Step } from '../components'
6 |
7 | const WizardContext = createContext(null);
8 |
9 | export type WizardProviderProps = PropsWithChildren<{
10 | initialValues?: Values;
11 | }>
12 |
13 | function isReactElement(child: ReactNode): child is ReactElement {
14 | return typeof child === 'object' && child !== null && 'type' in child;
15 | }
16 |
17 | /**
18 | * @typeParam Values Optional object to describe values being gathered by the wizard
19 | * @param props
20 | *
21 | * Create a routed wizard experience under a Router from [react-router](https://reactrouter.com)
22 | *
23 | *
24 | * @example Set up the Wizard under a BrowserRouter
25 | * ```tsx
26 | * function App() {
27 | * return (
28 | *
29 | * initialValues={{ firstName: '', lastName: '' }}>
30 | * } />
31 | * } />
32 | * } />
33 | *
34 | *
35 | * )
36 | * }
37 | * ```
38 | *
39 | *
40 | * @example An example step component
41 | * ```tsx
42 | * const First = () => {
43 | * const wizard = useWizardContext();
44 | *
45 | * const onSubmit = (event: FormEvent) => {
46 | * event.preventDefault();
47 | * const values = Object.fromEntries(new FormData(event.currentTarget))
48 | * wizard.goToNextStep({ values })
49 | * }
50 | *
51 | * return (
52 | * <>
53 | * {wizard.currentStep} step
54 | *
73 | *
74 | * )
75 | * }
76 | * ```
77 | **/
78 | export function Wizard({ children, initialValues = {} as Values }: WizardProviderProps) {
79 | if (typeof children !== 'object' || children === null) throw new Error('WizardProvider must have at least one child Step component')
80 |
81 | const steps: Array & RouteObject> = Children.map(children, child => {
82 | if (isReactElement(child) && child.type === Step) {
83 | return { ...child.props as StepConfig, path: child.props.name as string };
84 | }
85 | return null;
86 | })?.filter(Boolean) ?? [];
87 | const navigate = useNavigate();
88 | const location = useLocation();
89 | const wizard = useWizard(steps, initialValues, {
90 | navigate: () => {
91 | navigate(wizard.currentStep);
92 | }
93 | });
94 | const stepsWithRedirect = steps.concat({
95 | index: true,
96 | element: (),
97 | path: "/",
98 | name: 'index-redirect'
99 | });
100 | const step = useRoutes(stepsWithRedirect)
101 | const stepFromLocation = location.pathname.split('/').pop();
102 |
103 | useEffect(() => {
104 | if (stepFromLocation && stepFromLocation !== wizard.currentStep) {
105 | wizard.sync({ step: stepFromLocation })
106 | }
107 | }, [stepFromLocation, wizard])
108 |
109 | return (
110 |
111 | {step}
112 |
113 | )
114 | }
115 |
116 | /**
117 | * @typeParam Values - object describing the [[currentValues]] gathered by [[RoboWizard]]
118 | *
119 | * Access the [[RoboWizard]] from the [[Wizard]] Context Provider
120 | **/
121 | export function useWizardContext() {
122 | const wizard = useContext(WizardContext);
123 | if (wizard === null) throw new Error('useWizardContext must be used within WizardProvider')
124 | return wizard as RoboWizard;
125 | }
126 |
--------------------------------------------------------------------------------
/packages/react-router/src/index.ts:
--------------------------------------------------------------------------------
1 | export * from "./context";
2 | export * from "./components";
3 |
--------------------------------------------------------------------------------
/packages/react-router/test/index.test.tsx:
--------------------------------------------------------------------------------
1 | import { describe, it, expect } from 'vitest'
2 | import { render, screen, fireEvent } from '@testing-library/react'
3 | import { MemoryRouter, useNavigate } from 'react-router'
4 | import { Wizard, Step, useWizardContext } from '../src'
5 |
6 | function TestStep() {
7 | const wizard = useWizardContext()
8 | const navigate = useNavigate()
9 |
10 | return (
11 | <>
12 | {wizard.currentStep} step
13 |
14 |
15 |
16 | )
17 | }
18 |
19 | describe('Wizard', () => {
20 | const subject = () => (
21 |
22 |
23 | } />
24 | } />
25 | } />
26 |
27 |
28 | )
29 |
30 | it('navigates through steps', () => {
31 | render(subject());
32 |
33 | expect(screen.getByText('first step')).toBeTruthy();
34 |
35 | fireEvent.click(screen.getByText('Next'))
36 |
37 | expect(screen.getByText('second step')).toBeTruthy();
38 |
39 | fireEvent.click(screen.getByText('Next'))
40 |
41 | expect(screen.getByText('third step')).toBeTruthy();
42 |
43 | fireEvent.click(screen.getByText('Back'))
44 |
45 | expect(screen.getByText('second step')).toBeTruthy();
46 | })
47 | })
48 |
--------------------------------------------------------------------------------
/packages/react-router/test/setup.ts:
--------------------------------------------------------------------------------
1 | import '@testing-library/jest-dom'
2 |
--------------------------------------------------------------------------------
/packages/react-router/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "extends": "../../tsconfig.json",
3 | "include": [
4 | "./src",
5 | "./types"
6 | ],
7 | "exclude": [
8 | "node_modules",
9 | "test",
10 | "dist"
11 | ],
12 | "compilerOptions": {
13 | "rootDir": "src",
14 | "lib": [
15 | "DOM",
16 | "DOM.Iterable",
17 | "ES2019"
18 | ],
19 | "jsx": "react-jsx",
20 | "target": "es2020",
21 | "skipLibCheck": true
22 | }
23 | }
24 |
--------------------------------------------------------------------------------
/packages/react-router/vite.config.ts:
--------------------------------------------------------------------------------
1 | ///
2 |
3 | import path from 'path'
4 | import { defineConfig } from 'vite'
5 | import dts from 'vite-plugin-dts'
6 | import react from '@vitejs/plugin-react'
7 |
8 | export default defineConfig({
9 | build: {
10 | lib: {
11 | entry: path.resolve(__dirname, 'src/index.ts'),
12 | name: 'RoboWizardReactRouter',
13 | fileName: format => `robo-wizard_react-router.${format}.js`
14 | },
15 | sourcemap: true,
16 | rollupOptions: {
17 | external: ['react', 'react-dom', 'react-router'],
18 | output: {
19 | globals: {
20 | react: 'React',
21 | 'react-dom': 'ReactDom',
22 | 'react-router': 'ReactRouter'
23 | }
24 | }
25 | }
26 | },
27 | plugins: [dts(), react()],
28 | test: {
29 | globals: true,
30 | environment: 'jsdom',
31 | setupFiles: './test/setup.ts',
32 | }
33 | })
34 |
--------------------------------------------------------------------------------
/packages/react/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # @robo-wizard/react [1.1.0](https://github.com/HipsterBrown/robo-wizard/compare/@robo-wizard/react@1.0.0...@robo-wizard/react@1.1.0) (2022-12-20)
2 |
3 |
4 | ### Features
5 |
6 | * **react:** create Wizard, Step components ([#34](https://github.com/HipsterBrown/robo-wizard/issues/34)) ([fd13b0e](https://github.com/HipsterBrown/robo-wizard/commit/fd13b0e690c48db378ab3ed1a41fba1d77bc54a7))
7 |
--------------------------------------------------------------------------------
/packages/react/README.md:
--------------------------------------------------------------------------------
1 | # Robo Wizard React
2 |
3 | A library for building multi-step workflows in React.
4 |
5 | ## Getting Started
6 |
7 | ```
8 | npm i @robo-wizard/react
9 | ```
10 |
11 | Scaffold a basic wizard experience (bring your own form library as needed):
12 |
13 | ```tsx
14 | const App: React.FC = () => {
15 | const wizard = useWizard(['first-name', 'last-name', 'success'], { firstName: '', lastName: '' });
16 |
17 | const onSubmit = event => {
18 | event.preventDefault();
19 | const values = Object.fromEntries(new FormData(event.currentTarget))
20 | wizard.goToNextStep({ values });
21 | };
22 |
23 | return (
24 |
25 |
{wizard.currentStep} step
26 |
85 |
{wizard.currentStep} step
80 | *
99 | *
100 | * )
101 | * }
102 | * ```
103 | **/
104 | export function Wizard>({ children, initialValues = {} as Values }: WizardProviderProps) {
105 | const steps = createStepsFromChildren(children);
106 | const wizard = useWizard(steps, initialValues)
107 | const step = steps.find(({ name }) => name === wizard.currentStep)
108 |
109 | return (
110 |
111 | {step?.element}
112 |
113 | )
114 | }
115 |
116 | /**
117 | * @typeParam Values - object describing the [[currentValues]] gathered by [[RoboWizard]]
118 | *
119 | * Access the [[RoboWizard]] from the [[Wizard]] Context Provider
120 | **/
121 | export function useWizardContext() {
122 | const wizard = useContext(WizardContext);
123 | if (wizard === null) throw new Error('useWizardContext must be used within WizardProvider')
124 | return wizard as RoboWizard;
125 | }
126 |
--------------------------------------------------------------------------------
/packages/react/src/hooks/index.ts:
--------------------------------------------------------------------------------
1 | export * from "./use-wizard";
2 |
--------------------------------------------------------------------------------
/packages/react/src/hooks/use-wizard.ts:
--------------------------------------------------------------------------------
1 | import { useState, useReducer } from "react";
2 | import { createWizard, FlowStep, BaseValues } from "robo-wizard";
3 |
4 | /**
5 | * @typeParam Values Generic type for object of values being gathered through the wizard steps
6 | * @param steps Configuration of steps for the wizard, see [[FlowStep]]
7 | * @param initialValues Optional object with intial values to use when starting the wizard
8 | * @param actions Optional object with navigate field with a function to be called when entering a step
9 | *
10 | * @example Basic usage
11 | * ```tsx
12 | *
13 | * const App: React.FC = () => {
14 | * const wizard = useWizard(['first', 'second', 'third']);
15 |
16 | * const onSubmit: React.FormEventHandler = event => {
17 | * event.preventDefault();
18 | * const values = Object.fromEntries(new FormData(event.currentTarget))
19 | * wizard.goToNextStep({ values });
20 | * };
21 |
22 | * return (
23 | *
24 | *
{wizard.currentStep} step
25 | *
84 | *
}
40 | })
16 |