From aae5638888dac9d4f70213b71b1b0843f17e5038 Mon Sep 17 00:00:00 2001 From: "D.A. Kahn" Date: Wed, 26 Aug 2020 18:28:15 -0500 Subject: [PATCH 1/5] docs(Combobox): add mdx docs --- .../src/components/ComboBox/ComboBox-story.js | 42 +++++++++++-------- .../src/components/ComboBox/ComboBox.mdx | 30 +++++++++++++ 2 files changed, 55 insertions(+), 17 deletions(-) create mode 100644 packages/react/src/components/ComboBox/ComboBox.mdx diff --git a/packages/react/src/components/ComboBox/ComboBox-story.js b/packages/react/src/components/ComboBox/ComboBox-story.js index d9bddfe6b909..5b1e2fdff826 100644 --- a/packages/react/src/components/ComboBox/ComboBox-story.js +++ b/packages/react/src/components/ComboBox/ComboBox-story.js @@ -7,8 +7,9 @@ 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'; const items = [ { @@ -50,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...'), @@ -64,16 +87,7 @@ const props = () => ({ onChange: action('onChange'), }); -export default { - title: 'ComboBox', - decorators: [withKnobs], - - parameters: { - component: ComboBox, - }, -}; - -export const Default = () => ( +export const Playground = () => (
( />
); - -Default.parameters = { - info: { - text: 'ComboBox', - }, -}; diff --git a/packages/react/src/components/ComboBox/ComboBox.mdx b/packages/react/src/components/ComboBox/ComboBox.mdx new file mode 100644 index 000000000000..146007c80273 --- /dev/null +++ b/packages/react/src/components/ComboBox/ComboBox.mdx @@ -0,0 +1,30 @@ +import { Story, Props, Source, Preview } from '@storybook/addon-docs/blocks'; +import { withKnobs, boolean, select, text } from '@storybook/addon-knobs'; +import * as stories from './ComboBox-story.js'; +import ComboBox from '../ComboBox'; + +# ComboBox + +## Table of Contents + +- [Overview](#overview) +- [Component API](#component-api) +- [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 + + + +## 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.stories.mdx) From b8f12261661b674e05ca09e488ce00ce8ef1d43c Mon Sep 17 00:00:00 2001 From: "D.A. Kahn" Date: Thu, 17 Sep 2020 19:46:26 -0500 Subject: [PATCH 2/5] docs(combobox): add additional stories --- .../src/components/ComboBox/ComboBox-story.js | 26 ++++++++++++++ .../src/components/ComboBox/ComboBox.mdx | 36 +++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/packages/react/src/components/ComboBox/ComboBox-story.js b/packages/react/src/components/ComboBox/ComboBox-story.js index 5b1e2fdff826..7c8628a09e4c 100644 --- a/packages/react/src/components/ComboBox/ComboBox-story.js +++ b/packages/react/src/components/ComboBox/ComboBox-story.js @@ -96,3 +96,29 @@ export const Playground = () => ( /> ); + +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 146007c80273..60cfc9b586a4 100644 --- a/packages/react/src/components/ComboBox/ComboBox.mdx +++ b/packages/react/src/components/ComboBox/ComboBox.mdx @@ -20,6 +20,42 @@ and is typically used when there are a large amount of options to choose from. +## 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. + ## Component API From 02b6c55f308a787b7b5d4f9568a08bfd8bb4256c Mon Sep 17 00:00:00 2001 From: "D.A. Kahn" Date: Wed, 23 Sep 2020 21:36:06 -0500 Subject: [PATCH 3/5] docs(Combobox): add itemToString, itemToElement, etc examples --- .../src/components/ComboBox/ComboBox.mdx | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/packages/react/src/components/ComboBox/ComboBox.mdx b/packages/react/src/components/ComboBox/ComboBox.mdx index 60cfc9b586a4..7ee40e2bbe2d 100644 --- a/packages/react/src/components/ComboBox/ComboBox.mdx +++ b/packages/react/src/components/ComboBox/ComboBox.mdx @@ -56,6 +56,59 @@ 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 : '')} +/> +``` + ## Component API From 525d2ad0954ffa18661c9d45420eafdeb91144e1 Mon Sep 17 00:00:00 2001 From: "D.A. Kahn" Date: Fri, 25 Sep 2020 17:39:11 -0500 Subject: [PATCH 4/5] docs(Combobox): updated TOC and moved props table --- .../react/src/components/ComboBox/ComboBox.mdx | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/packages/react/src/components/ComboBox/ComboBox.mdx b/packages/react/src/components/ComboBox/ComboBox.mdx index 7ee40e2bbe2d..e58f12fab8df 100644 --- a/packages/react/src/components/ComboBox/ComboBox.mdx +++ b/packages/react/src/components/ComboBox/ComboBox.mdx @@ -9,6 +9,13 @@ import ComboBox from '../ComboBox'; - [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 @@ -20,6 +27,10 @@ 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 @@ -109,10 +120,6 @@ If the `items` array is not an array of strings, you'll need to use /> ``` -## Component API - - - ## Feedback Help us improve these docs by From 92192f052809580c14f5e2f7bfcdd5fff1871c68 Mon Sep 17 00:00:00 2001 From: TJ Egan Date: Mon, 28 Sep 2020 10:10:05 -0700 Subject: [PATCH 5/5] chore(docs): add source code links --- packages/react/src/components/ComboBox/ComboBox.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/react/src/components/ComboBox/ComboBox.mdx b/packages/react/src/components/ComboBox/ComboBox.mdx index e58f12fab8df..8df0494dc927 100644 --- a/packages/react/src/components/ComboBox/ComboBox.mdx +++ b/packages/react/src/components/ComboBox/ComboBox.mdx @@ -5,6 +5,12 @@ import ComboBox from '../ComboBox'; # ComboBox +[Source code](https://github.com/carbon-design-system/carbon/tree/master/packages/react/src/components/ComboBox) + |  +[Usage guidelines](https://www.carbondesignsystem.com/components/dropdown/usage#combo-box) + |  +[Accessibility](https://www.carbondesignsystem.com/components/dropdown/accessibility) + ## Table of Contents - [Overview](#overview)