From 1fbca23b6d42377345adce022edec0081870a5da Mon Sep 17 00:00:00 2001 From: TJ Egan Date: Thu, 20 Aug 2020 14:55:38 -0700 Subject: [PATCH] chore(docs): update DatePicker docs (#6689) * chore(docs): start updating DatePicker docs * chore(docs): add DatePicker prop docs * chore(docs): add references, add list styles Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> --- packages/react/.storybook/styles.scss | 4 + .../components/DatePicker/DatePicker-story.js | 156 ++---------- .../src/components/DatePicker/DatePicker.js | 108 ++++---- .../src/components/DatePicker/DatePicker.mdx | 239 ++++++++++++++++++ .../DatePickerInput/DatePickerInput.js | 4 +- 5 files changed, 323 insertions(+), 188 deletions(-) create mode 100644 packages/react/src/components/DatePicker/DatePicker.mdx diff --git a/packages/react/.storybook/styles.scss b/packages/react/.storybook/styles.scss index 937addf053cb..d74e50684871 100644 --- a/packages/react/.storybook/styles.scss +++ b/packages/react/.storybook/styles.scss @@ -99,3 +99,7 @@ $prefix: 'bx'; } } } + +.sbdocs-li { + list-style: circle; +} diff --git a/packages/react/src/components/DatePicker/DatePicker-story.js b/packages/react/src/components/DatePicker/DatePicker-story.js index 71a4c696a20d..5e48db83aea0 100644 --- a/packages/react/src/components/DatePicker/DatePicker-story.js +++ b/packages/react/src/components/DatePicker/DatePicker-story.js @@ -6,19 +6,11 @@ */ import React from 'react'; -import { action, decorateAction } from '@storybook/addon-actions'; - import { withKnobs, boolean, select, text } from '@storybook/addon-knobs'; import DatePicker from '../DatePicker'; import DatePickerInput from '../DatePickerInput'; import DatePickerSkeleton from '../DatePicker/DatePicker.Skeleton'; -import WithState from '../../tools/withState'; - -// Datepickers last argument contains an instance of flatpickr -// and will cause action logger to enter an infinite loop. Just don't log that argument -const datePickerOnChangeActions = decorateAction([ - (args) => args.slice(0, args.length - 2), -]); +import mdx from './DatePicker.mdx'; const patterns = { 'Short (d{1,2}/d{4})': '\\d{1,2}/\\d{4}', @@ -33,10 +25,9 @@ const sizes = { const props = { datePicker: () => ({ + dateFormat: text('The date format (dateFormat in )', 'm/d/Y'), id: 'date-picker', light: boolean('Light variant (light in )', false), - onChange: datePickerOnChangeActions('onPickerChange'), - onClose: action('onClose'), }), datePickerInput: () => ({ id: 'date-picker-input-id', @@ -68,8 +59,6 @@ const props = { 'Icon description (iconDescription in )', 'Icon description' ), - onClick: action('onClick'), - onChange: action('onInputChange'), }), }; @@ -84,152 +73,53 @@ export default { DatePickerInput, DatePickerSkeleton, }, + docs: { + page: mdx, + }, }, }; export const Simple = () => ( - )', false)} - datePickerType="simple"> - + + ); Simple.storyName = 'simple'; -Simple.parameters = { - info: { - text: 'A simple Date Picker consists of an input field and no calendar.', - }, -}; - -export const SingleWithCalendar = () => ( - )', 'm/d/Y')}> - console.log('click')} - {...props.datePickerInput()} - /> +export const Single = () => ( + + ); -SingleWithCalendar.storyName = 'single with calendar'; - -SingleWithCalendar.parameters = { - info: { - text: ` - A single Date Picker consists of an input field and a calendar. - `, - }, -}; +Single.storyName = 'single with calendar'; -export const RangeWithCalendar = () => { - const datePickerInputProps = props.datePickerInput(); +export const Range = () => { return ( - )', - 'm/d/Y' - )}> + ); }; -RangeWithCalendar.storyName = 'range with calendar'; - -RangeWithCalendar.parameters = { - info: { - text: ` - A range Date Picker consists of two input fields and a calendar. - `, - }, -}; +Range.storyName = 'range with calendar'; -export const RangeWithCalendarAndMinMaxDates = () => { - const datePickerInputProps = props.datePickerInput(); - return ( - - - - - ); -}; - -RangeWithCalendarAndMinMaxDates.storyName = - 'range with calendar and min/max dates'; - -RangeWithCalendarAndMinMaxDates.parameters = { - info: { - text: ` - A range Date Picker consists of two input fields and a calendar, and optionally, the minDate and maxDate fields. - `, - }, -}; - -export const FullyControlled = () => ( - - {({ state, setState }) => ( - <> - { - const value = eventOrDates.target - ? eventOrDates.target.value - : eventOrDates[0]; - setState({ date: value }); - }}> - - - - - )} - +export const DatePickerPlayground = () => ( + + + ); -FullyControlled.storyName = 'fully controlled'; - -FullyControlled.parameters = { - info: { - text: ` - If your application needs to control the value of the date picker and - be notified of any changes. - `, - }, -}; - export const Skeleton = () => ; Skeleton.storyName = 'skeleton'; - -Skeleton.parameters = { - info: { - text: ` - Placeholder skeleton state to use when content is loading. - `, - }, -}; diff --git a/packages/react/src/components/DatePicker/DatePicker.js b/packages/react/src/components/DatePicker/DatePicker.js index 285545b562c4..908b524f9f6d 100644 --- a/packages/react/src/components/DatePicker/DatePicker.js +++ b/packages/react/src/components/DatePicker/DatePicker.js @@ -151,58 +151,58 @@ export default class DatePicker extends Component { light: PropTypes.bool, /** - * The language locale used to format the days of the week, months, and numbers. - * - * * `ar` - Arabic - * * `at` - Austria - * * `be` - Belarusian - * * `bg` - Bulgarian - * * `bn` - Bangla - * * `cat` - Catalan - * * `cs` - Czech - * * `cy` - Welsh - * * `da` - Danish - * * `de` - German - * * `en` - English - * * `eo` - Esperanto - * * `es` - Spanish - * * `et` - Estonian - * * `fa` - Persian - * * `fi` - Finnish - * * `fr` - French - * * `gr` - Greek - * * `he` - Hebrew - * * `hi` - Hindi - * * `hr` - Croatian - * * `hu` - Hungarian - * * `id` - Indonesian - * * `it` - Italian - * * `ja` - Japanese - * * `ko` - Korean - * * `lt` - Lithuanian - * * `lv` - Latvian - * * `mk` - Macedonian - * * `mn` - Mongolian - * * `ms` - Malaysian - * * `my` - Burmese - * * `nl` - Dutch - * * `no` - Norwegian - * * `pa` - Punjabi - * * `pl` - Polish - * * `pt` - Portuguese - * * `ro` - Romanian - * * `si` - Sinhala - * * `sk` - Slovak - * * `sl` - Slovenian - * * `sq` - Albanian - * * `sr` - Serbian - * * `sv` - Swedish - * * `th` - Thai - * * `tr` - Turkish - * * `uk` - Ukrainian - * * `vn` - Vietnamese - * * `zh` - Mandarin - */ + * The language locale used to format the days of the week, months, and numbers. The full list of supported locales can be found here https://github.com/flatpickr/flatpickr/tree/master/src/l10n + * + * `ar` - Arabic + `at` - Austria + `be` - Belarusian + `bg` - Bulgarian + `bn` - Bangla + `cat` - Catalan + `cs` - Czech + `cy` - Welsh + `da` - Danish + `de` - German + `en` - English + `eo` - Esperanto + `es` - Spanish + `et` - Estonian + `fa` - Persian + `fi` - Finnish + `fr` - French + `gr` - Greek + `he` - Hebrew + `hi` - Hindi + `hr` - Croatian + `hu` - Hungarian + `id` - Indonesian + `it` - Italian + `ja` - Japanese + `ko` - Korean + `lt` - Lithuanian + `lv` - Latvian + `mk` - Macedonian + `mn` - Mongolian + `ms` - Malaysian + `my` - Burmese + `nl` - Dutch + `no` - Norwegian + `pa` - Punjabi + `pl` - Polish + `pt` - Portuguese + `ro` - Romanian + `si` - Sinhala + `sk` - Slovak + `sl` - Slovenian + `sq` - Albanian + `sr` - Serbian + `sv` - Swedish + `th` - Thai + `tr` - Turkish + `uk` - Ukrainian + `vn` - Vietnamese + `zh` - Mandarin + */ locale: PropTypes.oneOf([ 'ar', 'at', @@ -336,7 +336,9 @@ export default class DatePicker extends Component { maxDate: maxDate, plugins: [ datePickerType === 'range' - ? new carbonFlatpickrRangePlugin({ input: this.toInputField }) + ? new carbonFlatpickrRangePlugin({ + input: this.toInputField, + }) : () => {}, appendTo ? carbonFlatpickrAppendToPlugin({ diff --git a/packages/react/src/components/DatePicker/DatePicker.mdx b/packages/react/src/components/DatePicker/DatePicker.mdx new file mode 100644 index 000000000000..298ba1cae486 --- /dev/null +++ b/packages/react/src/components/DatePicker/DatePicker.mdx @@ -0,0 +1,239 @@ +import { Story, Props, Source, Preview } from '@storybook/addon-docs/blocks'; +import DatePicker from '../DatePicker'; +import DatePickerInput from '../DatePickerInput'; + +# Date Picker + + + + +- [Overview](#overview) + - [Simple DatePicker](#simple-datepicker) + - [Range Datepicker](#range-datepicker) + - [Skeleton state](#skeleton-state) +- [Component API](#component-api) + - [DatePicker `appendTo`](#datepicker-appendto) + - [DatePicker `className`](#datepicker-classname) + - [DatePicker `dateFormat`](#datepicker-dateformat) + - [DatePicker `datePickerType`](#datepicker-datepickertype) + - [DatePicker `light`](#datepicker-light) + - [DatePicker `locale`](#datepicker-locale) + - [DatePicker `maxDate`](#datepicker-maxdate) + - [DatePicker `minDate`](#datepicker-mindate) +- [References](#references) +- [Feedback](#feedback) + + + +## Overview + +Date pickers allow users to select a single or a range of dates. Pickers are +used to display past, present, or future dates. The kind of date (exact, +approximate, memorable) you are requesting from the user will determine which +picker is best to use. Each picker’s format can be customized depending on +location or need. The `DatePicker` component expects a `DatePickerInput` as a +child. + +### Simple DatePicker + +The simple date input provides the user with only a text field in which they can +manually input a date. It allows dates to be entered without adding unnecessary +interactions that come with the calendar menu or a dropdown. + + + + + +### Range Datepicker + +Calendar pickers default to showing today’s date when opened and only one month +is shown at a time. Calendar pickers allow users to navigate through months and +years, however they work best when used for recent or near future dates. + + + + + + +### Skeleton state + +You can use the `DatePickerSkeleton` component to render a skeleton variant of a +`DatePicker`. This is useful to display while an initial date range in your +`DatePicker` is being fetched from an external resource like an API. + + + + + +## Component API + + + +### DatePicker `appendTo` + +By default, the `DatePicker` menu will be appended to the end of the `body` +element. If you would like to attach it to a different node, you can specify a +DOM element with the `appendTo` prop. + +```jsx +const node = document.querySelector('#my-node'); + +...; +``` + +### DatePicker `className` + +The className prop passed into `DatePicker` will be forwarded along to the +underlying wrapper `div.bx--date-picker` element. This is useful for specifying +a custom class name for layout. + +```jsx +... +``` + +### DatePicker `dateFormat` + +You can use the `dateFormat` prop to change how the selected date is displayed +in the input. For a complete list of supported date formatting tokens, please +see the Flatpickr +[documentation](https://flatpickr.js.org/formatting/#date-formatting-tokens) + + + + + +```jsx + + + +``` + +### DatePicker `datePickerType` + +There are three supported variations of `DatePicker` in Carbon. + +- `simple` will render a simple text input _without_ a calendar dropdown. +- `single` will render a a single text input _with_ a calendar dropdown. +- `range` will indicate that multiple `DatePicker` inputs will be rendered. Two + `DatePickerInput` will need to be provided as children. + +```jsx + + + + +``` + +### DatePicker `light` + +In certain circumstances, a `DatePicker` will exist on a container element with +the same background color. To improve contrast, you can use the `light` property +to toggle the light variant of the `DatePicker`. + +```jsx +... +``` + +### DatePicker `locale` + +The `locale` prop can be used to help with internationalization. For best +results, combine with the `dateFormat` prop. We pass this under the hood to the +FlatPickr instance. A complete list of valid locales can be found in the +[component API](#component-api) section + + + + + +```jsx +// Load Norwegian text with the proper date format + + + +``` + +### DatePicker `maxDate` + +Limits the date selection to any date before the date specified. The string +format depends on the `locale` specified. For example, the top example below is +using the default US date format, and the one below it is using the same format +as the `locale` prop example. One is setting it as September 1st, and the other +is setting it as January 9th. + + + + +
+ + + + +```jsx + + + + + + +; +``` + +### DatePicker `minDate` + +Works similarly to the `maxDate` prop. [See above](#datepicker-maxdate). + + + + + +### DatePicker `value` + +By default `DatePicker` will set the current date as its value. If you'd like to +start this at a different date, you can pass in a date string or date object. + + + + +
+ + + + +```jsx + + + + + + + +``` + +## References + +- The `DatePicker` component utilizes Flatpickr under the hood. We will pass any + extra options down to the FlatPickr instance. For a full list of options, + please see the [Flatpickr docs](https://flatpickr.js.org/options/) +- The `DatePickerInput` takes in similar props to the `TextInput` component, + such as `size` and `placeholder`. For more information on these props, check + out the `TextInput` page. + +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon/edit/master/packages/react/src/components/DatePicker/DatePicker.mdx). diff --git a/packages/react/src/components/DatePickerInput/DatePickerInput.js b/packages/react/src/components/DatePickerInput/DatePickerInput.js index 9186b439adeb..c5e3c12d40ad 100644 --- a/packages/react/src/components/DatePickerInput/DatePickerInput.js +++ b/packages/react/src/components/DatePickerInput/DatePickerInput.js @@ -40,7 +40,7 @@ export default class DatePickerInput extends Component { iconDescription: PropTypes.string, /** - * Specify an id that unique identifies the + * Specify an id that uniquely identifies the `` */ id: PropTypes.string.isRequired, @@ -103,7 +103,7 @@ export default class DatePickerInput extends Component { size: PropTypes.oneOf(['sm', 'xl']), /** - * Specify the type of the + * Specify the type of the `` */ type: PropTypes.string, };