docs: improve documentation (#1001)

* add netlify redirects in toml file * overall improvements for docsite * more docs improvements * fix examples for useCombobox * remove playground styles * remove playground styles again * refresh useSelect examples * refresh useCombobox examples * refresh useMultiple * add material example for combobox
downshift-js · Apr 18, 2020 · 50a476d · 50a476d
1 parent b24693c
commit 50a476d
Show file tree

Hide file tree

Showing 10 changed files with 605 additions and 289 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
   <br>
 </h1>
 <p align="center" style="font-size: 1.2rem;">Primitives to build simple, flexible, WAI-ARIA compliant React
-autocomplete/dropdown/select/combobox components</p>
+autocomplete, combobox or select dropdown components.</p>
 
 > See
 > [the intro blog post](https://kentcdodds.com/blog/introducing-downshift-for-react)
@@ -30,9 +30,10 @@ autocomplete/dropdown/select/combobox components</p>
 
 ## The problem
 
-You need an autocomplete/dropdown/select experience in your application and you
+You need an autocomplete/combobox/select experience in your application and you
 want it to be accessible. You also want it to be simple and flexible to account
-for your use cases.
+for your use cases. Finally, it should follow the [ARIA design
+pattern][combobox-aria] for a combobox.
 
 ## This solution
 
@@ -99,7 +100,6 @@ the library treeshaked (pruned) and given only the code you need. Since version
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-
 - [Installation](#installation)
 - [Usage](#usage)
 - [Basic Props](#basic-props)
@@ -1406,6 +1406,7 @@ Thanks goes to these people ([emoji key][emojis]):
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors][all-contributors] specification.
@@ -1477,3 +1478,5 @@ MIT
 [multiple-selection-readme]:
   https://github.com/downshift-js/downshift/tree/master/src/hooks/useMultipleSelection
 [bundle-phobia-link]: https://bundlephobia.com/[email protected]
+[combobox-aria]:
+  https://www.w3.org/TR/wai-aria-practices/examples/combobox/aria1.1pattern/listbox-combo.html
diff --git a/docs/downshift/downshift.mdx b/docs/downshift/downshift.mdx
@@ -1,21 +1,34 @@
 ---
-name: Component
-menu: Downshift
-route: /downshift/component
+name: Downshift
+menu: Components
+route: /downshift
 ---
 
 import {useState} from 'react'
 import {Playground} from 'docz'
 import Downshift from '../../src'
-import {items, menuStyles, comboboxStyles, playgroundStyles} from '../utils'
+import {items, menuStyles, comboboxStyles} from '../utils'
 
 # Downshift
 
 ## Introduction
 
 The `Downshift` component has been developed in order to provide accessibility
 and functionality to a `combobox` component, described by the corresponding
-[ARIA docs](https://www.w3.org/TR/wai-aria-practices/examples/combobox/aria1.1pattern/listbox-combo.html).
+[ARIA design pattern][combobox-aria].
+
+This is a component that controls user interactions and state for you so you can
+create autocomplete/combobox or select components. It uses a [render
+prop][use-a-render-prop] which gives you maximum flexibility with a minimal API
+because you are responsible for the rendering of everything and you simply apply
+props to what you're rendering.
+
+This differs from other solutions which render things for their use case and
+then expose many options to allow for extensibility resulting in a bigger API
+that is less flexible as well as making the implementation more complicated and
+harder to contribute to.
+
+## Props used in examples
 
 In the examples below, we use the `Downshift` hook and destructure from its
 result the getter props and state variables. The hooks also has the
@@ -41,10 +54,11 @@ information check out the
 ## Important
 
 If you are new to `Downshift` then maybe you should fist check
-[useCombobox](/hooks/use-combobox) which should provide the same functionality
+[useCombobox](/use-combobox) which should provide the same functionality
 but as a hook. If it's not suiting your use case then come back here. Also, if
 you need just a `select` dropdown without a text input, then check
-[useSelect](/hooks/use-select).
+[useSelect](/use-select). Finally, for a multiple selection, you can check the
+[useMultipleSelection](/use-multiple-selection) hook.
 
 As far as the component is concerned, you can use it in two ways, both of them
 illustrated below.
@@ -54,7 +68,7 @@ There is an _straightforward_ way, which allows you to wrap your whole
 `combobox` HTML structure is not correct, and screen readers will not widely
 support it.
 
-There is also the _not-so-straightforward-way_ which allows you to respect the
+There is also the _not-so-straightforward-way_ which allows you to follow the
 `combobox` HTML structure and you should aim for this one. Here you will use
 `getRootProps` on the element that wraps your `<input>` and then you will add
 the `<ul>` on the same level with the wrapper. More details on each of these
@@ -76,18 +90,20 @@ wrapper element that contains the `<input>` and optionally the trigger button.
 
 [CodeSandbox](https://codesandbox.io/s/simple-downshift-with-getrootprops-example-24s13)
 
-<Playground style={playgroundStyles}>
+<Playground>
   {() => {
     const DropdownCombobox = () => {
       const [inputItems, setInputItems] = useState(items)
       return (
-        <Downshift onInputValueChange={inputValue => {
-          setInputItems(
-            items.filter(item =>
-              item.toLowerCase().startsWith(inputValue.toLowerCase()),
+        <Downshift
+          onInputValueChange={inputValue => {
+            setInputItems(
+              items.filter(item =>
+                item.toLowerCase().startsWith(inputValue.toLowerCase()),
+              ),
             )
-          )
-        }}>
+          }}
+        >
           {({
             getInputProps,
             getItemProps,
@@ -98,36 +114,40 @@ wrapper element that contains the `<input>` and optionally the trigger button.
             highlightedIndex,
             isOpen,
           }) => (
-        <>
-          <label {...getLabelProps()}>Choose an element:</label>
-          <div style={comboboxStyles} {...getRootProps({}, {suppressRefError: true})}>
-            <input {...getInputProps()} />
-            <button {...getToggleButtonProps()} aria-label={'toggle menu'}>
-              &#8595;
-            </button>
-          </div>
-          <ul {...getMenuProps()} style={menuStyles}>
-            {isOpen &&
-              inputItems.map((item, index) => (
-                <li
-                  style={
-                    highlightedIndex === index
-                      ? {backgroundColor: '#bde4ff'}
-                      : {}
-                  }
-                  key={`${item}${index}`}
-                  {...getItemProps({item, index})}
-                >
-                  {item}
-                </li>
-              ))}
-          </ul>
-        </>
-      )}
-      </Downshift>
-    )}
+            <>
+              <label {...getLabelProps()}>Choose an element:</label>
+              <div
+                className="ds-combobox"
+                {...getRootProps({}, {suppressRefError: true})}
+              >
+                <input {...getInputProps()} />
+                <button {...getToggleButtonProps()} aria-label={'toggle menu'}>
+                  &#8595;
+                </button>
+              </div>
+              <ul {...getMenuProps()} style={menuStyles}>
+                {isOpen &&
+                  inputItems.map((item, index) => (
+                    <li
+                      style={
+                        highlightedIndex === index
+                          ? {backgroundColor: '#bde4ff'}
+                          : {}
+                      }
+                      key={`${item}${index}`}
+                      {...getItemProps({item, index})}
+                    >
+                      {item}
+                    </li>
+                  ))}
+              </ul>
+            </>
+          )}
+        </Downshift>
+      )
+    }
     return <DropdownCombobox />
-}}
+  }}
 </Playground>
 
 ## Usage without `getRootProps`
@@ -142,18 +162,20 @@ example above or to `useCombobox` hook.
 
 [CodeSandbox](https://codesandbox.io/s/usecombobox-usage-evufg)
 
-<Playground style={playgroundStyles}>
+<Playground>
   {() => {
     const DropdownCombobox = () => {
       const [inputItems, setInputItems] = useState(items)
       return (
-        <Downshift onInputValueChange={inputValue => {
-          setInputItems(
-            items.filter(item =>
-              item.toLowerCase().startsWith(inputValue.toLowerCase()),
+        <Downshift
+          onInputValueChange={inputValue => {
+            setInputItems(
+              items.filter(item =>
+                item.toLowerCase().startsWith(inputValue.toLowerCase()),
+              ),
             )
-          )
-        }}>
+          }}
+        >
           {({
             getInputProps,
             getItemProps,
@@ -163,32 +185,38 @@ example above or to `useCombobox` hook.
             highlightedIndex,
             isOpen,
           }) => (
-        <div>
-          <label {...getLabelProps()}>Choose an element:</label>
-          <input {...getInputProps()} />
-          <button {...getToggleButtonProps()} aria-label={'toggle menu'}>
-            &#8595;
-          </button>
-          <ul {...getMenuProps()} style={menuStyles}>
-            {isOpen &&
-              inputItems.map((item, index) => (
-                <li
-                  style={
-                    highlightedIndex === index
-                      ? {backgroundColor: '#bde4ff'}
-                      : {}
-                  }
-                  key={`${item}${index}`}
-                  {...getItemProps({item, index})}
-                >
-                  {item}
-                </li>
-              ))}
-          </ul>
-        </div>
-      )}
-      </Downshift>
-    )}
+            <div>
+              <label {...getLabelProps()}>Choose an element:</label>
+              <input {...getInputProps()} />
+              <button {...getToggleButtonProps()} aria-label={'toggle menu'}>
+                &#8595;
+              </button>
+              <ul {...getMenuProps()} style={menuStyles}>
+                {isOpen &&
+                  inputItems.map((item, index) => (
+                    <li
+                      style={
+                        highlightedIndex === index
+                          ? {backgroundColor: '#bde4ff'}
+                          : {}
+                      }
+                      key={`${item}${index}`}
+                      {...getItemProps({item, index})}
+                    >
+                      {item}
+                    </li>
+                  ))}
+              </ul>
+            </div>
+          )}
+        </Downshift>
+      )
+    }
     return <DropdownCombobox />
-}}
+  }}
 </Playground>
+
+[combobox-aria]:
+  https://www.w3.org/TR/wai-aria-practices/examples/combobox/aria1.1pattern/listbox-combo.html
+[use-a-render-prop]:
+  https://cdb.reacttraining.com/use-a-render-prop-50de598f11ce