Skip to content

Commit e610f54

Browse files
atomicpagesatomicpages
committed
docs(:pencil:) mo' docs
- More IA reorganization - Adding docs for components - Adding notes regarding tree-shaking and building from source
1 parent d285de7 commit e610f54

File tree

8 files changed

+553
-59
lines changed

8 files changed

+553
-59
lines changed

‎docs/docs/checkbox.md

+258
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
---
2+
id: checkbox
3+
title: Checkbox
4+
---
5+
6+
At the heart and soul of every application is at least one checkbox. It might be a terms and conditions agreement,
7+
"Do not sell" CCPA notice, or something else; whatever it is, `pretty-checkbox-react` (PCR) has your back.
8+
9+
## Shapes, Variants, & States
10+
11+
There's no "one size fits all" for input controls like Checkbox.
12+
Thankfully, PCR allows you to represent Checkbox in various ways via the `shape` and `variant` prop
13+
for pre-bundled fun. See the [`shapes`](props/shapes-size) docs for more details.
14+
15+
```jsx live
16+
<>
17+
<Checkbox>Regular</Checkbox>
18+
<Checkbox shape="curve" variant="thick">
19+
Thick Curve
20+
</Checkbox>
21+
<Checkbox shape="round" variant="fill">
22+
Fill Round
23+
</Checkbox>
24+
</>
25+
```
26+
27+
### Disabled &amp; Locked
28+
29+
Of course `disabled` is supported, but there's also a secondary state called `locked`.
30+
See the [states](props/states) docs for more details.
31+
32+
```jsx live
33+
<>
34+
<Checkbox>Regular</Checkbox>
35+
<Checkbox disabled>Disabled</Checkbox>
36+
<Checkbox locked>Locked</Checkbox>
37+
</>
38+
```
39+
40+
### Scalability
41+
42+
Out of the box, PCR offers a `bigger` prop to make all input controls just a tad bit larger.
43+
For more fine-grained control check out the [size docs](props/shapes-size#size).
44+
45+
```jsx live
46+
<>
47+
<Checkbox>Regular</Checkbox>
48+
<Checkbox bigger>Bigger</Checkbox>
49+
</>
50+
```
51+
52+
## Uncontrolled
53+
54+
`Checkbox` forwards `refs` to the input element :smile:.
55+
See the [uncontrolled component docs](main-concepts/uncontrolled) for more info.
56+
57+
```jsx live
58+
function App() {
59+
const ref = React.useRef(null);
60+
61+
React.useEffect(() => {
62+
if (ref.current) {
63+
console.log(ref.current);
64+
}
65+
}, []);
66+
67+
return <Checkbox ref={ref}>Uncontrolled Usage</Checkbox>;
68+
}
69+
```
70+
71+
## Controlled
72+
73+
PCR exposes helpful state hooks to make managing state a breeze. For checkbox you should use `useCheckboxState`.
74+
See the [controlled component docs](main-concepts/controlled) for more info.
75+
76+
### Boolean Checkboxes
77+
78+
For simple yes/no, or true/false usage, you can use the hook as-is without any extra config needed 😲:
79+
80+
```jsx live
81+
function App() {
82+
const checkbox = useCheckboxState();
83+
84+
return <Checkbox {...checkbox}>Checked: {checkbox.state + ''}</Checkbox>;
85+
}
86+
```
87+
88+
### Named Checkbox
89+
90+
PCR supports checkbox controls with a `value` prop too! The resulting state will be an `array` &ndash; even if it's a single item.
91+
92+
:::note
93+
The initial `state` will be `false` unless specified otherwise.
94+
:::
95+
96+
```jsx live
97+
function App() {
98+
const checkbox = useCheckboxState();
99+
100+
return (
101+
<Checkbox value="active" {...checkbox}>
102+
Checked: {checkbox.state + ''}
103+
</Checkbox>
104+
);
105+
}
106+
```
107+
108+
### Grouped Controls
109+
110+
PCR represents _named_ checkboxes as an array which allows us to use the same state hook for multiple checkboxes!
111+
Not only does this keep your code clean, but keeps th footprint of PCR extra small :sunglasses:
112+
113+
```jsx live
114+
function App() {
115+
const fruits = ['apples', 'oranges', 'bananas'];
116+
const checkbox = useCheckboxState({ state: [] });
117+
118+
return (
119+
<>
120+
{fruits.map(fruit => (
121+
<Checkbox value={fruit} {...checkbox}>
122+
{fruit}
123+
</Checkbox>
124+
))}
125+
<p>Selected items: {checkbox.state.join(', ')}</p>
126+
</>
127+
);
128+
}
129+
```
130+
131+
## Indeterminate
132+
133+
`indeterminate`, or tri-state checkboxes are relative niche, but have their place in the wild.
134+
PCR supports state-driven tri-state as well as an `indeterminate` prop for uncontrolled usage.
135+
136+
### Uncontrolled Indeterminate
137+
138+
Using the `indeterminate`, PCR sets two things:
139+
140+
1. `aria-checked` to `mixed`
141+
2. `indeterminate` property on the `input` element to true
142+
143+
:::info
144+
As of `alpha.2` the second point isn't true. A fixed is needed on pretty-checkbox to
145+
ensure `:indeterminate` selectors style the checkbo as checked.
146+
:::
147+
148+
```jsx live
149+
<Checkbox indeterminate>Indeterminate</Checkbox>
150+
```
151+
152+
### Controlled Indeterminate
153+
154+
For controlled usage, you can use the `indeterminate` _or_ use "indeterminate" as a special state keyword:
155+
156+
```jsx live
157+
function App() {
158+
const checkbox = useCheckboxState();
159+
160+
return (
161+
<>
162+
<Checkbox
163+
icon={
164+
<i
165+
className={`mdi mdi-${
166+
checkbox.state === 'indeterminate' ? 'minus' : 'check'
167+
}`}
168+
/>
169+
}
170+
{...checkbox}>
171+
Controlled Indeterminate
172+
</Checkbox>
173+
<button
174+
onClick={() => {
175+
checkbox.setState('indeterminate');
176+
}}>
177+
Indeterminate
178+
</button>
179+
</>
180+
);
181+
}
182+
```
183+
184+
Controlled indeterminates have a whole host of usages including trees!
185+
186+
<p>
187+
<small>
188+
Credit where credit is due. This example is{' '}
189+
<a href="https://reakit.io/docs/checkbox/#indeterminate-or-mixed-state">
190+
adapted from reakit
191+
</a>
192+
</small>
193+
</p>
194+
195+
```jsx live
196+
(function () {
197+
function useTreeState({ values }) {
198+
const group = useCheckboxState();
199+
const items = useCheckboxState();
200+
201+
// updates items when group is toggled
202+
React.useEffect(() => {
203+
if (group.state === true) {
204+
items.setState(values);
205+
} else if (group.state === false) {
206+
items.setState([]);
207+
}
208+
}, [group.state]);
209+
210+
// updates group when items is toggled
211+
React.useEffect(() => {
212+
if (items.state.length === values.length) {
213+
group.setState(true);
214+
} else if (items.state.length) {
215+
group.setState('indeterminate');
216+
} else {
217+
group.setState(false);
218+
}
219+
}, [items.state]);
220+
221+
return { group, items };
222+
}
223+
224+
function Icon({ state }) {
225+
return <i className={`icon mdi mdi-${state === 'indeterminate' ? 'minus' : 'check'}`} />;
226+
}
227+
228+
function App() {
229+
const values = ['Apple', 'Orange', 'Watermelon'];
230+
const { group, items } = useTreeState({ values });
231+
232+
return (
233+
<ul>
234+
<li>
235+
<label>
236+
<Checkbox icon={<Icon {...group} />} data-type="icon" {...group}>
237+
Fruits
238+
</Checkbox>
239+
</label>
240+
</li>
241+
<ul>
242+
{values.map((value, i) => (
243+
<li key={i}>
244+
<label>
245+
<Checkbox icon={<Icon />} data-type="icon" {...items} value={value}>
246+
{value}
247+
</Checkbox>
248+
</label>
249+
</li>
250+
))}
251+
</ul>
252+
</ul>
253+
);
254+
}
255+
256+
return App;
257+
})()
258+
```

‎docs/docs/checkbox.mdx

-57
This file was deleted.

‎docs/docs/main-concepts/components.md

+46
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,49 @@ Custom `data-*` attribute or something else? PCR has your back :sunglasses:
9797
```jsx
9898
<Radio data-testid="tlr">@testing-library/react ready</Radio>
9999
```
100+
101+
## Tree Shaking & Modules
102+
103+
PCR is totally modular and is [side-effect free](https://webpack.js.org/guides/tree-shaking/#clarifying-tree-shaking-and-sideeffects). If you're using webpack, snowpack, or another modern bundler that supports [ES Modules or CJS Modules](https://webpack.js.org/concepts/modules/).
104+
105+
### Transpiling from Source
106+
107+
In addition to ES and CJS modules, PCR also packages the transpiled typescript source code for special application needs 🙂. A typical flow might look like:
108+
109+
```js title="App.js"
110+
import { Checkbox, useCheckboxState } from 'pretty-checkbox-react/dist-src/index';
111+
112+
// use your imports
113+
```
114+
115+
If you're using babel make sure you have the following:
116+
117+
- presets
118+
- `@babel/preset-react`
119+
- plugins
120+
- `@babel/plugin-proposal-optional-chaining`
121+
122+
```js title="webpack.config.js"
123+
module.exports = {
124+
module: {
125+
rules: [
126+
{
127+
test: /\.jsx?/,
128+
// prevent exclusion of PCR from node_modules
129+
// to allow babel to transpile for you
130+
exclude: /(?!node_modules\/pretty-checkbox-react\/)/,
131+
options: {
132+
presets: [
133+
[
134+
'@babel/preset-env',
135+
{ corejs: 3 }
136+
],
137+
'@babel/preset-react'
138+
],
139+
plugins: ['@babel/plugin-proposal-optional-chaining'],
140+
},
141+
},
142+
],
143+
},
144+
};
145+
```

‎docs/docs/main-concepts/controlled.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ Not sold on the PCR's super awesome hooks? That's okay :cry:. Because our hooks
111111
### React `useState`
112112

113113
:::note
114-
Passing `setState` while optional, is recommended since PCR internally handles different types of state. For full control use the `checked` prop instead of passing `setState`.
114+
Passing `setState` while optional, is recommended since PCR internally handles different types of state. For full control use the `checked` prop.
115115
:::
116116

117117
```jsx live

‎docs/docs/main-concepts/i18n.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
id: internationalization
3+
title: Internationalization
4+
---
5+
6+
PCR doesn't contain any locale-specific strings that are rendered in the browser. Since you, the super awesome user of PCR, provides all the content, it seamlessly integrates into your i18n/l10n/g11n solution :smile:
7+
8+
## RTL Usage
9+
10+
PCR is a stylish wrapper around standard HTML elements which means LTR support requires **zero configuration**.
11+
12+
```jsx live
13+
<Checkbox dir="rtl">Hello</Checkbox>
14+
```

0 commit comments

Comments
 (0)