Skip to content

Commit 9487371

Browse files
devrntdevrnt
authored
Merge pull request #10 from devrnt/docs/readme
Docs/readme
2 parents acc670e + 824c3a3 commit 9487371

File tree

3 files changed

+218
-134
lines changed

3 files changed

+218
-134
lines changed

‎README.md‎

Lines changed: 203 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -1,160 +1,230 @@
1-
# TSDX React User Guide
1+
<p align="center"><img src="https://raw.githubusercontent.com/devrnt/react-use-wizard/master/assets/logo.svg" alt="react-use-wizard logo" height="120px" style="margin-top: 20px;"/></p>
2+
<h1 align="center">react-use-wizard</h1>
3+
<p align="center">A React wizard (stepper) builder without the hassle, powered by hooks.</p>
24

3-
Congrats! You just saved yourself hours of work by bootstrapping this project with TSDX. Let’s get you oriented with what’s here and how to use it.
5+
<p align="center">
6+
<img alt="ci" src="https://github.com/devrnt/react-use-wizard/workflows/CI/badge.svg?branch=master">
7+
<img alt="version" src="https://img.shields.io/npm/v/react-use-wizard.svg" />
8+
<img alt="downloads" src="https://badgen.net/npm/dt/react-use-wizard" />
9+
<img alt="minzipped size" src="https://badgen.net/bundlephobia/minzip/react-use-wizard">
10+
<img alt="known vulnerabilities" src="https://snyk.io/test/github/devrnt/react-use-wizard/badge.svg">
11+
</p>
412

5-
> This TSDX setup is meant for developing React component libraries (not apps!) that can be published to NPM. If you’re looking to build a React-based app, you should use `create-react-app`, `razzle`, `nextjs`, `gatsby`, or `react-static`.
13+
## Features
614

7-
> If you’re new to TypeScript and React, checkout [this handy cheatsheet](https://github.com/sw-yx/react-typescript-cheatsheet/)
15+
- Hooks
16+
- Focused on logic
17+
- No UI restrictions
18+
- Written in TypeScript
19+
- Documented, self explaining methods
820

9-
## Commands
21+
## Installation
1022

11-
TSDX scaffolds your new library inside `/src`, and also sets up a [Parcel-based](https://parceljs.org) playground for it inside `/example`.
12-
13-
The recommended workflow is to run TSDX in one terminal:
14-
15-
```bash
16-
npm start # or yarn start
1723
```
18-
19-
This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`.
20-
21-
Then run the example inside another:
22-
23-
```bash
24-
cd example
25-
npm i # or yarn to install dependencies
26-
npm start # or yarn start
24+
yarn add react-use-wizard
2725
```
2826

29-
The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**, we use [Parcel's aliasing](https://parceljs.org/module_resolution.html#aliases).
30-
31-
To do a one-off build, use `npm run build` or `yarn build`.
32-
33-
To run tests, use `npm test` or `yarn test`.
34-
35-
## Configuration
36-
37-
Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly.
38-
39-
### Jest
40-
41-
Jest tests are set up to run with `npm test` or `yarn test`.
42-
43-
### Bundle analysis
44-
45-
Calculates the real cost of your library using [size-limit](https://github.com/ai/size-limit) with `npm run size` and visulize it with `npm run analyze`.
46-
47-
#### Setup Files
48-
49-
This is the folder structure we set up for you:
50-
51-
```txt
52-
/example
53-
index.html
54-
index.tsx # test your component here in a demo app
55-
package.json
56-
tsconfig.json
57-
/src
58-
index.tsx # EDIT THIS
59-
/test
60-
blah.test.tsx # EDIT THIS
61-
.gitignore
62-
package.json
63-
README.md # EDIT THIS
64-
tsconfig.json
65-
```
66-
67-
#### React Testing Library
68-
69-
We do not set up `react-testing-library` for you yet, we welcome contributions and documentation on this.
70-
71-
### Rollup
72-
73-
TSDX uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details.
74-
75-
### TypeScript
76-
77-
`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `react` for `jsx`. Adjust according to your needs.
78-
79-
## Continuous Integration
80-
81-
### GitHub Actions
82-
83-
Two actions are added by default:
84-
85-
- `main` which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix
86-
- `size` which comments cost comparison of your library on every pull request using [`size-limit`](https://github.com/ai/size-limit)
87-
88-
## Optimizations
89-
90-
Please see the main `tsdx` [optimizations docs](https://github.com/palmerhq/tsdx#optimizations). In particular, know that you can take advantage of development-only optimizations:
27+
## Quickstart
9128

9229
```js
93-
// ./types/index.d.ts
94-
declare var __DEV__: boolean;
95-
96-
// inside your code...
97-
if (__DEV__) {
98-
console.log('foo');
99-
}
30+
import * as React from 'react';
31+
32+
import { Wizard } from 'react-use-wizard';
33+
34+
const App = () => (
35+
<Wizard>
36+
<Step1 />
37+
<Step2 />
38+
<Step3 />
39+
</Wizard>
40+
);
41+
42+
const Step1 = () => {
43+
const { handleStep, previousStep, nextStep } = useWizard();
44+
45+
// Attach a handler
46+
handleStep(() => {
47+
alert('Going to step 2');
48+
});
49+
50+
return (
51+
<>
52+
<button onClick={previousStep}>Previous ⏮️</button>
53+
<button onClick={nextStep}>Next ⏭</button>
54+
</>
55+
);
56+
};
10057
```
10158

102-
You can also choose to install and use [invariant](https://github.com/palmerhq/tsdx#invariant) and [warning](https://github.com/palmerhq/tsdx#warning) functions.
103-
104-
## Module Formats
105-
106-
CJS, ESModules, and UMD module formats are supported.
107-
108-
The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found.
109-
110-
## Deploying the Example Playground
111-
112-
The Playground is just a simple [Parcel](https://parceljs.org) app, you can deploy it anywhere you would normally deploy that. Here are some guidelines for **manually** deploying with the Netlify CLI (`npm i -g netlify-cli`):
113-
114-
```bash
115-
cd example # if not already in the example folder
116-
npm run build # builds to dist
117-
netlify deploy # deploy the dist folder
59+
## Links
60+
61+
- [API](#api)
62+
- [Playground](#playground)
63+
- [Examples](#examples)
64+
- [Async](#async)
65+
- [Animation](#animation)
66+
- [Advanced](#advanced)
67+
68+
## API
69+
70+
- [Wizard](#wizard)
71+
- [useWizard](#usewizard)
72+
73+
### Wizard
74+
75+
`Wizard` is used to wrap your steps. Each child component will be treated as an individual step. You can set a shared `footer` and `header` that always should be in your steps. Example: pass an action button component that contain a "previous" and "next" button.
76+
77+
Place the `Wizard` around it and that's it.
78+
79+
#### Props
80+
81+
| name | type | description | required | default |
82+
| ---------- | --------------- | ------------------------------------------------------------- | -------- | ------- |
83+
| startIndex | number | Start index to indicate the wizard to start at the given step | ❌ | 0 |
84+
| header | React.ReactNode | Header that is shown above the active step | ❌ | |
85+
| footer | React.ReactNode | Footer that is shown below the active stepstep | ❌ | |
86+
| children | React.ReactNode | Each child component will be treated as an individual step | ✔️ |
87+
88+
#### Example
89+
90+
```javascript
91+
const Header = () => <p>I am the header component</p>;
92+
93+
const Footer = () => {
94+
const {
95+
nextStep,
96+
previousStep,
97+
activeStep,
98+
isLastStep,
99+
isFirstStep,
100+
} = useWizard();
101+
102+
return (
103+
<>
104+
<div>
105+
Has next step: {!isLastStep ? '✅' : '⛔'}
106+
<br />
107+
Has previous step : {!isFirstStep ? '✅' : '⛔'}
108+
</div>
109+
Active step: {activeStep + 1} <br />
110+
<button onClick={previousStep}>Previous</button>
111+
<button onClick={nextStep}>Next</button>
112+
</>
113+
);
114+
};
115+
116+
const App = () => {
117+
return (
118+
<Wizard startIndex={0} header={<Header />} footer={<Footer />}>
119+
<Step1 />
120+
<Step2 />
121+
<Step3 />
122+
</Wizard>
123+
);
124+
};
118125
```
119126

120-
Alternatively, if you already have a git repo connected, you can set up continuous deployment with Netlify:
121-
122-
```bash
123-
netlify init
124-
# build command: yarn build && cd example && yarn && yarn build
125-
# directory to deploy: example/dist
126-
# pick yes for netlify.toml
127+
### useWizard
128+
129+
Used to retrieve all methods and props bundled with the Wizard.
130+
131+
Make sure `Wizard` is wrapped around your component when calling `useWizard`.
132+
133+
**Remark** - You can't use `useWizard` in the same component where `Wizard` is used.
134+
135+
#### Methods
136+
137+
| name | type | description |
138+
| ----------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------- |
139+
| nextStep | () => Promise<void> | Go to the next step |
140+
| previousStep | () => void | Go to the previous step |
141+
| handleStep | (handler: Handler) => void | Connect a callback that will be called when calling `nextStep`. `handler` can be either sync or async |
142+
| isLoading | (props?: IntercomProps) => void | \* Will reflect the handler promise state: will be `true` if the handler promise is pending and |
143+
| \* `false` when the handler is either fulfilled or rejected |
144+
| activeStep | number | The current active step of the wizard |
145+
| isFirstStep | boolean | Indicate if the current step is the first step (aka no previous step) |
146+
| isLastStep | boolean | Indicate if the current step is the last step (aka no next step) |
147+
| |
148+
149+
#### Example
150+
151+
```javascript
152+
import * as React from 'react';
153+
154+
import { Wizard, useWiard } from 'react-use-wizard';
155+
156+
const App = () => (
157+
<Wizard>
158+
<Step1 />
159+
<Step2 />
160+
<Step3 />
161+
</Wizard>
162+
);
163+
164+
const Step1 = () => {
165+
const {
166+
isLoading,
167+
isLastStep,
168+
isFirstStep,
169+
activeStep,
170+
previousStep,
171+
nextStep,
172+
handleStep,
173+
} = useWizard();
174+
175+
handleStep(() => {
176+
alert('Going to step 2');
177+
});
178+
179+
return (
180+
<>
181+
<p>Step 1</p>
182+
{isLoading && <p>loading...</p>}
183+
<button onClick={previousStep}>Previous</button>
184+
<button onClick={nextStep}>Next</button>
185+
<div>
186+
Has next step: {!isLastStep ? '✅' : '⛔'}
187+
<br />
188+
Has previous step : {!isFirstStep ? '✅' : '⛔'}
189+
</div>
190+
Active step: {activeStep + 1} <br />
191+
</>
192+
);
193+
};
127194
```
128195

129-
## Named Exports
130-
131-
Per Palmer Group guidelines, [always use named exports.](https://github.com/palmerhq/typescript#exports) Code split inside your React app instead of your React library.
196+
It's recommended to put the shared components in the `header` or `footer` in the `Wizard` to avoid duplication.
132197

133-
## Including Styles
198+
## Examples
199+
Go to [examples](https://github.com/devrnt/react-use-wiard/tree/master/examples) to check see some examples
134200

135-
There are many ways to ship styles, including with CSS-in-JS. TSDX has no opinion on this, configure how you like.
201+
## Async
136202

137-
For vanilla CSS, you can include it at the root directory and add it to the `files` section in your `package.json`, so that it can be imported separately by your users and run through their bundler's loader.
203+
You can connect an async step handler to a step as well. Make sure to make to either pass an async function or return a promise (async) function:
138204

139-
## Publishing to NPM
205+
```ts
206+
const Step1 = () => {
207+
const { handleStep } = useWizard();
140208

141-
We recommend using [np](https://github.com/sindresorhus/np).
209+
// Async function
210+
handleStep(async () => {
211+
await fetch(...);
212+
});
142213

143-
## Usage with Lerna
214+
// Return promise
215+
handleStep(() => {
216+
return fetch(...);
217+
});
144218

145-
When creating a new package with TSDX within a project set up with Lerna, you might encounter a `Cannot resolve dependency` error when trying to run the `example` project. To fix that you will need to make changes to the `package.json` file _inside the `example` directory_.
219+
...
220+
}
221+
```
146222

147-
The problem is that due to the nature of how dependencies are installed in Lerna projects, the aliases in the example project's `package.json` might not point to the right place, as those dependencies might have been installed in the root of your Lerna project.
223+
The `isLoading` of `useWizard` will indicate the loading state of the step when calling `nextStep`. If no errors are thrown the wizard will go to the next step, so no need to call this manually. If an error is thrown in the conencted function the wizard will just stay at the same step and will rethrow the error. (So you can try-catch in your connected function).
148224

149-
Change the `alias` to point to where those packages are actually installed. This depends on the directory structure of your Lerna project, so the actual path might be different from the diff below.
225+
If an async function is connected the `isLoading` of `useWizard` will indicate the loading state of the function.
150226

151-
```diff
152-
"alias": {
153-
- "react": "../node_modules/react",
154-
- "react-dom": "../node_modules/react-dom"
155-
+ "react": "../../../node_modules/react",
156-
+ "react-dom": "../../../node_modules/react-dom"
157-
},
158-
```
227+
## Animation
228+
Since `react-use-wizard` is focused to manage the logic of a wizard doesn't mean you can't add some animation by your own. Add any animation library that you like. I highly suggest (https://www.framer.com/motion/)[framer-motion].
159229

160-
An alternative to fixing this problem would be to remove aliases altogether and define the dependencies referenced as aliases as dev dependencies instead. [However, that might cause other problems.](https://github.com/palmerhq/tsdx/issues/64)
230+
Checkout this (https://github.com/devrnt/react-use-wizard/blob/docs/readme/example/components/animatedStep.tsx)[example] to see an animation to a step can be added.

0 commit comments

Comments
 (0)