From 36027c6ce317d6c4e9be03587627c6fa70673d13 Mon Sep 17 00:00:00 2001 From: DAK <40970507+dakahn@users.noreply.github.com> Date: Mon, 28 Sep 2020 12:29:25 -0500 Subject: [PATCH] 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 Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> --- .../src/components/ComboBox/ComboBox-story.js | 68 ++++++++--- .../src/components/ComboBox/ComboBox.mdx | 109 ++++++++++++++++-- 2 files changed, 151 insertions(+), 26 deletions(-) diff --git a/packages/react/src/components/ComboBox/ComboBox-story.js b/packages/react/src/components/ComboBox/ComboBox-story.js index 61ca41526580..d941a7288355 100644 --- 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 = () => ( +
+ (item ? item.text : '')} + placeholder="Filter..." + titleText="ComboBox title" + helperText="Combobox helper text" + /> +
+); + 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 = () => (
(
); -Default.parameters = { - info: { - text: 'ComboBox', - }, -}; +export const disabled = () => ( +
+ (item ? item.text : '')} + placeholder="Filter..." + titleText="ComboBox title" + helperText="Combobox helper text" + /> +
+); + +export const light = () => ( +
+ (item ? item.text : '')} + placeholder="Filter..." + titleText="ComboBox title" + helperText="Combobox helper text" + /> +
+); diff --git a/packages/react/src/components/ComboBox/ComboBox.mdx b/packages/react/src/components/ComboBox/ComboBox.mdx index 7291a12294e6..8df0494dc927 100644 --- 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 - - - [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) - - ## 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. + - + ## Component API - + + +## 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. + + + + + +## Light + +The light prop should never be used against a light background. The form element +must have proper contrast against the pages background. + + + + + +## 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'] + +; +``` + +## `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. + +``` + + item ? ( + + {item.text} 🔥 + + ) : ( + '' + ) + } + 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. + +``` + (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)