docs(:pencil:) mo' docs

- More IA reorganization - Adding docs for components - Adding notes regarding tree-shaking and building from source
atomicpages · Sep 9, 2020 · e610f54 · e610f54
1 parent d285de7
commit e610f54
Show file tree

Hide file tree

Showing 8 changed files with 553 additions and 59 deletions.
diff --git a/docs/docs/checkbox.md b/docs/docs/checkbox.md
@@ -0,0 +1,258 @@
+---
+id: checkbox
+title: Checkbox
+---
+
+At the heart and soul of every application is at least one checkbox. It might be a terms and conditions agreement,
+"Do not sell" CCPA notice, or something else; whatever it is, `pretty-checkbox-react` (PCR) has your back.
+
+## Shapes, Variants, & States
+
+There's no "one size fits all" for input controls like Checkbox.
+Thankfully, PCR allows you to represent Checkbox in various ways via the `shape` and `variant` prop
+for pre-bundled fun. See the [`shapes`](props/shapes-size) docs for more details.
+
+```jsx live
+<>
+    <Checkbox>Regular</Checkbox>
+    <Checkbox shape="curve" variant="thick">
+        Thick Curve
+    </Checkbox>
+    <Checkbox shape="round" variant="fill">
+        Fill Round
+    </Checkbox>
+</>
+```
+
+### Disabled &amp; Locked
+
+Of course `disabled` is supported, but there's also a secondary state called `locked`.
+See the [states](props/states) docs for more details.
+
+```jsx live
+<>
+    <Checkbox>Regular</Checkbox>
+    <Checkbox disabled>Disabled</Checkbox>
+    <Checkbox locked>Locked</Checkbox>
+</>
+```
+
+### Scalability
+
+Out of the box, PCR offers a `bigger` prop to make all input controls just a tad bit larger.
+For more fine-grained control check out the [size docs](props/shapes-size#size).
+
+```jsx live
+<>
+    <Checkbox>Regular</Checkbox>
+    <Checkbox bigger>Bigger</Checkbox>
+</>
+```
+
+## Uncontrolled
+
+`Checkbox` forwards `refs` to the input element :smile:.
+See the [uncontrolled component docs](main-concepts/uncontrolled) for more info.
+
+```jsx live
+function App() {
+    const ref = React.useRef(null);
+
+    React.useEffect(() => {
+        if (ref.current) {
+            console.log(ref.current);
+        }
+    }, []);
+
+    return <Checkbox ref={ref}>Uncontrolled Usage</Checkbox>;
+}
+```
+
+## Controlled
+
+PCR exposes helpful state hooks to make managing state a breeze. For checkbox you should use `useCheckboxState`.
+See the [controlled component docs](main-concepts/controlled) for more info.
+
+### Boolean Checkboxes
+
+For simple yes/no, or true/false usage, you can use the hook as-is without any extra config needed 😲:
+
+```jsx live
+function App() {
+    const checkbox = useCheckboxState();
+
+    return <Checkbox {...checkbox}>Checked: {checkbox.state + ''}</Checkbox>;
+}
+```
+
+### Named Checkbox
+
+PCR supports checkbox controls with a `value` prop too! The resulting state will be an `array` &ndash; even if it's a single item.
+
+:::note
+The initial `state` will be `false` unless specified otherwise.
+:::
+
+```jsx live
+function App() {
+    const checkbox = useCheckboxState();
+
+    return (
+        <Checkbox value="active" {...checkbox}>
+            Checked: {checkbox.state + ''}
+        </Checkbox>
+    );
+}
+```
+
+### Grouped Controls
+
+PCR represents _named_ checkboxes as an array which allows us to use the same state hook for multiple checkboxes!
+Not only does this keep your code clean, but keeps th footprint of PCR extra small :sunglasses:
+
+```jsx live
+function App() {
+    const fruits = ['apples', 'oranges', 'bananas'];
+    const checkbox = useCheckboxState({ state: [] });
+
+    return (
+        <>
+            {fruits.map(fruit => (
+                <Checkbox value={fruit} {...checkbox}>
+                    {fruit}
+                </Checkbox>
+            ))}
+            <p>Selected items: {checkbox.state.join(', ')}</p>
+        </>
+    );
+}
+```
+
+## Indeterminate
+
+`indeterminate`, or tri-state checkboxes are relative niche, but have their place in the wild.
+PCR supports state-driven tri-state as well as an `indeterminate` prop for uncontrolled usage.
+
+### Uncontrolled Indeterminate
+
+Using the `indeterminate`, PCR sets two things:
+
+1. `aria-checked` to `mixed`
+2. `indeterminate` property on the `input` element to true
+
+:::info
+As of `alpha.2` the second point isn't true. A fixed is needed on pretty-checkbox to
+ensure `:indeterminate` selectors style the checkbo as checked.
+:::
+
+```jsx live
+<Checkbox indeterminate>Indeterminate</Checkbox>
+```
+
+### Controlled Indeterminate
+
+For controlled usage, you can use the `indeterminate` _or_ use "indeterminate" as a special state keyword:
+
+```jsx live
+function App() {
+    const checkbox = useCheckboxState();
+
+    return (
+        <>
+            <Checkbox
+                icon={
+                    <i
+                        className={`mdi mdi-${
+                            checkbox.state === 'indeterminate' ? 'minus' : 'check'
+                        }`}
+                    />
+                }
+                {...checkbox}>
+                Controlled Indeterminate
+            </Checkbox>
+            <button
+                onClick={() => {
+                    checkbox.setState('indeterminate');
+                }}>
+                Indeterminate
+            </button>
+        </>
+    );
+}
+```
+
+Controlled indeterminates have a whole host of usages including trees!
+
+<p>
+    <small>
+        Credit where credit is due. This example is{' '}
+        <a href="https://reakit.io/docs/checkbox/#indeterminate-or-mixed-state">
+            adapted from reakit
+        </a>
+    </small>
+</p>
+
+```jsx live
+(function () {
+    function useTreeState({ values }) {
+        const group = useCheckboxState();
+        const items = useCheckboxState();
+
+        // updates items when group is toggled
+        React.useEffect(() => {
+            if (group.state === true) {
+                items.setState(values);
+            } else if (group.state === false) {
+                items.setState([]);
+            }
+        }, [group.state]);
+
+        // updates group when items is toggled
+        React.useEffect(() => {
+            if (items.state.length === values.length) {
+                group.setState(true);
+            } else if (items.state.length) {
+                group.setState('indeterminate');
+            } else {
+                group.setState(false);
+            }
+        }, [items.state]);
+
+        return { group, items };
+    }
+
+    function Icon({ state }) {
+        return <i className={`icon mdi mdi-${state === 'indeterminate' ? 'minus' : 'check'}`} />;
+    }
+
+    function App() {
+        const values = ['Apple', 'Orange', 'Watermelon'];
+        const { group, items } = useTreeState({ values });
+
+        return (
+            <ul>
+                <li>
+                    <label>
+                        <Checkbox icon={<Icon {...group} />} data-type="icon" {...group}>
+                            Fruits
+                        </Checkbox>
+                    </label>
+                </li>
+                <ul>
+                    {values.map((value, i) => (
+                        <li key={i}>
+                            <label>
+                                <Checkbox icon={<Icon />} data-type="icon" {...items} value={value}>
+                                    {value}
+                                </Checkbox>
+                            </label>
+                        </li>
+                    ))}
+                </ul>
+            </ul>
+        );
+    }
+
+    return App;
+})()
+```
diff --git a/docs/docs/checkbox.mdx b/docs/docs/checkbox.mdx
diff --git a/docs/docs/main-concepts/components.md b/docs/docs/main-concepts/components.md
@@ -97,3 +97,49 @@ Custom `data-*` attribute or something else? PCR has your back :sunglasses:
 ```jsx
 <Radio data-testid="tlr">@testing-library/react ready</Radio>
 ```
+
+## Tree Shaking & Modules
+
+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/).
+
+### Transpiling from Source
+
+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:
+
+```js title="App.js"
+import { Checkbox, useCheckboxState } from 'pretty-checkbox-react/dist-src/index';
+
+// use your imports
+```
+
+If you're using babel make sure you have the following:
+
+-   presets
+    -   `@babel/preset-react`
+-   plugins
+    -   `@babel/plugin-proposal-optional-chaining`
+
+```js title="webpack.config.js"
+module.exports = {
+    module: {
+        rules: [
+            {
+                test: /\.jsx?/,
+                // prevent exclusion of PCR from node_modules
+                // to allow babel to transpile for you
+                exclude: /(?!node_modules\/pretty-checkbox-react\/)/,
+                options: {
+                    presets: [
+                        [
+                            '@babel/preset-env',
+                            { corejs: 3 }
+                        ],
+                        '@babel/preset-react'
+                    ],
+                    plugins: ['@babel/plugin-proposal-optional-chaining'],
+                },
+            },
+        ],
+    },
+};
+```
diff --git a/docs/docs/main-concepts/controlled.md b/docs/docs/main-concepts/controlled.md
@@ -111,7 +111,7 @@ Not sold on the PCR's super awesome hooks? That's okay :cry:. Because our hooks
 ### React `useState`
 
 :::note
-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`.
+Passing `setState` while optional, is recommended since PCR internally handles different types of state. For full control use the `checked` prop.
 :::
 
 ```jsx live

diff --git a/docs/docs/main-concepts/i18n.md b/docs/docs/main-concepts/i18n.md
@@ -0,0 +1,14 @@
+---
+id: internationalization
+title: Internationalization
+---
+
+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:
+
+## RTL Usage
+
+PCR is a stylish wrapper around standard HTML elements which means LTR support requires **zero configuration**.
+
+```jsx live
+<Checkbox dir="rtl">Hello</Checkbox>
+```