From d97c2cad8b8ffefdd05c459807ea7921e88675a2 Mon Sep 17 00:00:00 2001 From: TJ Egan Date: Tue, 18 Aug 2020 12:07:54 -0700 Subject: [PATCH 1/3] chore(docs): start updating DatePicker docs --- .../components/DatePicker/DatePicker-story.js | 204 ++++++++---------- .../src/components/DatePicker/DatePicker.js | 108 +++++----- .../src/components/DatePicker/DatePicker.mdx | 77 +++++++ 3 files changed, 225 insertions(+), 164 deletions(-) create mode 100644 packages/react/src/components/DatePicker/DatePicker.mdx diff --git a/packages/react/src/components/DatePicker/DatePicker-story.js b/packages/react/src/components/DatePicker/DatePicker-story.js index 71a4c696a20d..572dd1a130d0 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,15 +73,15 @@ export default { DatePickerInput, DatePickerSkeleton, }, + docs: { + page: mdx, + }, }, }; export const Simple = () => ( - )', false)} - datePickerType="simple"> - + + ); @@ -104,21 +93,15 @@ Simple.parameters = { }, }; -export const SingleWithCalendar = () => ( - )', 'm/d/Y')}> - console.log('click')} - {...props.datePickerInput()} - /> +export const Single = () => ( + + ); -SingleWithCalendar.storyName = 'single with calendar'; +Single.storyName = 'single with calendar'; -SingleWithCalendar.parameters = { +Single.parameters = { info: { text: ` A single Date Picker consists of an input field and a calendar. @@ -126,31 +109,24 @@ SingleWithCalendar.parameters = { }, }; -export const RangeWithCalendar = () => { - const datePickerInputProps = props.datePickerInput(); +export const Range = () => { return ( - )', - 'm/d/Y' - )}> + ); }; -RangeWithCalendar.storyName = 'range with calendar'; +Range.storyName = 'range with calendar'; -RangeWithCalendar.parameters = { +Range.parameters = { info: { text: ` A range Date Picker consists of two input fields and a calendar. @@ -158,78 +134,84 @@ RangeWithCalendar.parameters = { }, }; -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 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 }); +// }}> +// +// +// +// +// )} +// +// ); + +// 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. - `, - }, -}; +// 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..780ba86bed79 --- /dev/null +++ b/packages/react/src/components/DatePicker/DatePicker.mdx @@ -0,0 +1,77 @@ +import { Story, Props, Source, Preview } from '@storybook/addon-docs/blocks'; +import DatePicker from '../DatePicker'; +import DatePickerInput from '../DatePickerInput'; + +# Date Picker + + + + +- [Overview](#overview) +- [Component API](#component-api) + - [DatePicker `className`](#datepicker-classname) +- [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. + +### 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 `className` + +The className prop passed into `DatePicker` will be forwarded along to the +underlying wrapper `div.bx--content-switcher` element. This is useful for +specifying a custom class name for layout. + +```jsx +... +``` + +## References + +## 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). From 451a741e89c4c656bcb1fcc833cce94d4734a943 Mon Sep 17 00:00:00 2001 From: TJ Egan Date: Wed, 19 Aug 2020 13:45:29 -0700 Subject: [PATCH 2/3] chore(docs): add DatePicker prop docs --- .../components/DatePicker/DatePicker-story.js | 94 ----------- .../src/components/DatePicker/DatePicker.mdx | 158 +++++++++++++++++- 2 files changed, 156 insertions(+), 96 deletions(-) diff --git a/packages/react/src/components/DatePicker/DatePicker-story.js b/packages/react/src/components/DatePicker/DatePicker-story.js index 572dd1a130d0..d975b2fc0bd5 100644 --- a/packages/react/src/components/DatePicker/DatePicker-story.js +++ b/packages/react/src/components/DatePicker/DatePicker-story.js @@ -87,12 +87,6 @@ export const Simple = () => ( Simple.storyName = 'simple'; -Simple.parameters = { - info: { - text: 'A simple Date Picker consists of an input field and no calendar.', - }, -}; - export const Single = () => ( @@ -101,14 +95,6 @@ export const Single = () => ( Single.storyName = 'single with calendar'; -Single.parameters = { - info: { - text: ` - A single Date Picker consists of an input field and a calendar. - `, - }, -}; - export const Range = () => { return ( @@ -126,92 +112,12 @@ export const Range = () => { Range.storyName = 'range with calendar'; -Range.parameters = { - info: { - text: ` - A range Date Picker consists of two input fields and a calendar. - `, - }, -}; - export const DatePickerPlayground = () => ( ); -// 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 }); -// }}> -// -// -// -// -// )} -// -// ); - -// 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.mdx b/packages/react/src/components/DatePicker/DatePicker.mdx index 780ba86bed79..cdd70a491a9c 100644 --- a/packages/react/src/components/DatePicker/DatePicker.mdx +++ b/packages/react/src/components/DatePicker/DatePicker.mdx @@ -8,8 +8,18 @@ import DatePickerInput from '../DatePickerInput'; - [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) @@ -58,16 +68,160 @@ You can use the `DatePickerSkeleton` component to render a skeleton variant of a +### 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--content-switcher` element. This is useful for -specifying a custom class name for layout. +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 ## Feedback From 9ea683ca870164d06aa1110e1dc43d0b8b07519c Mon Sep 17 00:00:00 2001 From: TJ Egan Date: Thu, 20 Aug 2020 11:13:32 -0700 Subject: [PATCH 3/3] chore(docs): add references, add list styles --- packages/react/.storybook/styles.scss | 4 ++++ .../src/components/DatePicker/DatePicker-story.js | 6 ++++-- .../react/src/components/DatePicker/DatePicker.mdx | 10 +++++++++- .../src/components/DatePickerInput/DatePickerInput.js | 4 ++-- 4 files changed, 19 insertions(+), 5 deletions(-) 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 d975b2fc0bd5..5e48db83aea0 100644 --- a/packages/react/src/components/DatePicker/DatePicker-story.js +++ b/packages/react/src/components/DatePicker/DatePicker-story.js @@ -81,7 +81,7 @@ export default { export const Simple = () => ( - + ); @@ -89,7 +89,7 @@ Simple.storyName = 'simple'; export const Single = () => ( - + ); @@ -101,10 +101,12 @@ export const Range = () => { ); diff --git a/packages/react/src/components/DatePicker/DatePicker.mdx b/packages/react/src/components/DatePicker/DatePicker.mdx index cdd70a491a9c..298ba1cae486 100644 --- a/packages/react/src/components/DatePicker/DatePicker.mdx +++ b/packages/react/src/components/DatePicker/DatePicker.mdx @@ -31,7 +31,8 @@ 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. +location or need. The `DatePicker` component expects a `DatePickerInput` as a +child. ### Simple DatePicker @@ -224,6 +225,13 @@ start this at a different date, you can pass in a date string or date object. ## 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 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, };