docs(Combobox): update dev docs; add mdx docs (#6734)

* docs(Combobox): add mdx docs * docs(combobox): add additional stories * docs(Combobox): add itemToString, itemToElement, etc examples * docs(Combobox): updated TOC and moved props table * chore(docs): add source code links Co-authored-by: TJ Egan <tw15egan@gmail.com> Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
carbon-design-system · Sep 28, 2020 · 36027c6 · 36027c6
1 parent f1bf6c9
commit 36027c6
Show file tree

Hide file tree

Showing 2 changed files with 151 additions and 26 deletions.
diff --git a/packages/react/src/components/ComboBox/ComboBox-story.js b/packages/react/src/components/ComboBox/ComboBox-story.js
@@ -7,7 +7,7 @@
 
 import React from 'react';
 import { action } from '@storybook/addon-actions';
-import { withKnobs, boolean, select, text } from '@storybook/addon-knobs';
+import { boolean, select, text } from '@storybook/addon-knobs';
 import ComboBox from '../ComboBox';
 import mdx from './ComboBox.mdx';
 
@@ -51,6 +51,28 @@ const directions = {
   'Top ': 'top',
 };
 
+export default {
+  title: 'ComboBox',
+  component: ComboBox,
+  parameters: {
+    docs: {
+      page: mdx,
+    },
+  },
+};
+
+export const combobox = () => (
+  <div style={{ width: 300 }}>
+    <ComboBox
+      items={items}
+      itemToString={(item) => (item ? item.text : '')}
+      placeholder="Filter..."
+      titleText="ComboBox title"
+      helperText="Combobox helper text"
+    />
+  </div>
+);
+
 const props = () => ({
   id: text('Combobox ID (id)', 'carbon-combobox-example'),
   placeholder: text('Placeholder text (placeholder)', 'Filter...'),
@@ -66,19 +88,7 @@ const props = () => ({
   onToggleClick: action('onClick'),
 });
 
-export default {
-  title: 'ComboBox',
-  decorators: [withKnobs],
-
-  parameters: {
-    component: ComboBox,
-    docs: {
-      page: mdx,
-    },
-  },
-};
-
-export const Default = () => (
+export const Playground = () => (
   <div style={{ width: 300 }}>
     <ComboBox
       items={items}
@@ -88,8 +98,28 @@ export const Default = () => (
   </div>
 );
 
-Default.parameters = {
-  info: {
-    text: 'ComboBox',
-  },
-};
+export const disabled = () => (
+  <div style={{ width: 300 }}>
+    <ComboBox
+      disabled
+      items={items}
+      itemToString={(item) => (item ? item.text : '')}
+      placeholder="Filter..."
+      titleText="ComboBox title"
+      helperText="Combobox helper text"
+    />
+  </div>
+);
+
+export const light = () => (
+  <div style={{ width: 300 }}>
+    <ComboBox
+      light
+      items={items}
+      itemToString={(item) => (item ? item.text : '')}
+      placeholder="Filter..."
+      titleText="ComboBox title"
+      helperText="Combobox helper text"
+    />
+  </div>
+);
diff --git a/packages/react/src/components/ComboBox/ComboBox.mdx b/packages/react/src/components/ComboBox/ComboBox.mdx
@@ -13,25 +13,120 @@ import ComboBox from '../ComboBox';
 
 ## Table of Contents
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-
 - [Overview](#overview)
 - [Component API](#component-api)
+- [Disabled](#disabled)
+- [Light](#light)
+- [downshiftProps](#combobox-downshiftprops)
+- [Placeholder and labeling](#placeholders-and-labeling)
+- [initialSelectedItem](#initialselecteditem)
+- [itemToElement](#itemtoelement)
+- [itemToString](#itemtostring)
 - [Feedback](#feedback)
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
+A combobox allows the user to make a selection from a predefined list of options
+and is typically used when there are a large amount of options to choose from.
+
 <Preview>
-  <Story id="combobox--default" />
+  <Story id="combobox--combobox" />
 </Preview>
 
 ## Component API
 
-<Props />
+<Props sort="asc" />
+
+## Disabled
+
+A disabled comobobox is available but should not be used as the sole means of
+conveying information. For example, if the user must complete a previous form
+input before moving on to the combobox, make sure to make that clear to the user
+via an error state on the previous form element in adition to disabling the next
+element.
+
+<Preview>
+  <Story id="combobox--disabled" />
+</Preview>
+
+## Light
+
+The light prop should never be used against a light background. The form element
+must have proper contrast against the pages background.
+
+<Preview>
+  <Story id="combobox--light" />
+</Preview>
+
+## Combobox `downshiftProps`
+
+Our `Combobox` component utilizes [Downshift](https://www.downshift-js.com/)
+under the hood to help provide complex yet accessible custom dropdown
+components. We provide access to the built in Downshift features with this prop.
+For more information, checkout the Downshift prop
+[documentation](https://www.downshift-js.com/downshift#props-used-in-examples)
+
+## Placeholders and Labeling
+
+The placeholder is not a replacement for a label under any circumstances
+including space restraints. Placeholders should be used to provide additive
+information regarding the format of the input. In all cases a label is required
+_in addition to_ a placeholder.
+
+## `initialSelectedItem`
+
+If you want the Combobox to render with a value already selected, but do not
+want to fully control the component, you can use `initialSelectedItem`
+
+```
+const items = ['Option 1', 'Option 2', 'Option 3']
+
+<Combobox initialSelectedItem={items[2]} />;
+```
+
+## `itemToElement`
+
+The Combobox takes in an `items` array and can then be formatted by
+`itemToElement` and `itemToString`. `itemToElement` allows you to wrap each
+dropdown item in a custom element.
+
+```
+<Combobox
+  items={[
+    { id: 'option-0', text: 'Option 0'  },
+    { id: 'option-1', text: 'Option 1'  },
+    { id: 'option-2', text: 'Option 2'  },
+  ]}
+  itemToElement={(item) =>
+    item ? (
+      <span className="test" style={{ color: 'red'  }}>
+        {item.text} 🔥
+      </span>
+    ) : (
+      ''
+    )
+  }
+  label="Select an option..."
+/>
+```
+
+## `itemToString`
+
+If the `items` array is not an array of strings, you'll need to use
+`itemToString` to grab the text to be used as the `Combobox` item text.
+
+```
+<Combobox
+  items={[
+    { id: 'option-0', text: 'Option 0' },
+    { id: 'option-1', text: 'Option 1' },
+    { id: 'option-2', text: 'Option 2' },
+  ]}
+  itemToString={(item) => (item ? item.text : '')}
+/>
+```
 
 ## Feedback
 
 Help us improve these docs by
-[editing this file on GitHub](https://github.com/carbon-design-system/carbon/edit/master/packages/react/src/components/ComboBox/ComboBox.mdx)
+[editing this file on GitHub](https://github.com/carbon-design-system/carbon/edit/master/packages/react/src/components/ComboBox/ComboBox.stories.mdx)