chore(docs): add DatePicker prop docs

carbon-design-system · Aug 19, 2020 · 81a4c28 · 81a4c28
1 parent 305ef8f
commit 81a4c28
Show file tree

Hide file tree

Showing 2 changed files with 156 additions and 96 deletions.
diff --git 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 = () => (
   <DatePicker datePickerType="single">
     <DatePickerInput placeholder="mm/dd/yyyy" />
@@ -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 (
     <DatePicker datePickerType="range">
@@ -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 = () => (
   <DatePicker {...props.datePicker()} datePickerType="single">
     <DatePickerInput {...props.datePickerInput()} />
   </DatePicker>
 );
 
-// export const RangeWithCalendarAndMinMaxDates = () => {
-//   const datePickerInputProps = props.datePickerInput();
-//   return (
-//     <DatePicker
-//       {...props.datePicker()}
-//       minDate="1/10/2020"
-//       maxDate="1/20/2020"
-//       datePickerType="range"
-//       dateFormat="m/d/Y">
-//       <DatePickerInput {...datePickerInputProps} id="date-picker-input-id" />
-//       <DatePickerInput {...datePickerInputProps} id="date-picker-input-id-2" />
-//     </DatePicker>
-//   );
-// };
-
-// 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 = () => (
-//   <WithState initialState={{ date: '' }}>
-//     {({ state, setState }) => (
-//       <>
-//         <DatePicker
-//           datePickerType="single"
-//           dateFormat="m/d/Y"
-//           value={state.date}
-//           onChange={(eventOrDates) => {
-//             const value = eventOrDates.target
-//               ? eventOrDates.target.value
-//               : eventOrDates[0];
-//             setState({ date: value });
-//           }}>
-//           <DatePickerInput
-//             {...props.datePickerInput()}
-//             id="date-picker-input-id"
-//           />
-//         </DatePicker>
-//         <button type="button" onClick={() => setState({ date: '01/01/2011' })}>
-//           Click me to set to 01/01/2011
-//         </button>
-//       </>
-//     )}
-//   </WithState>
-// );
-
-// 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 = () => <DatePickerSkeleton range />;
 
 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
@@ -8,8 +8,18 @@ import DatePickerInput from '../DatePickerInput';
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 - [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
 
 <Props />
 
+### 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 appendTo={node}>...</DatePicker>;
+```
+
 ### 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 className="some-class">...</DatePicker>
 ```
 
+### 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)
+
+<DatePicker datePickerType="single" dateFormat="Y-m-d">
+  <DatePickerInput placeholder="yyyy-mm-dd" />
+</DatePicker>
+
+```jsx
+<DatePicker datePickerType="single" dateFormat="Y-m-d">
+  <DatePickerInput placeholder="mm/dd/yyyy" />
+</DatePicker>
+```
+
+### 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 datePickerType="range">
+  <DatePickerInput placeholder="Start" />
+  <DatePickerInput placeholder="End" />
+</DatePicker>
+```
+
+### 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 light>...</DatePicker>
+```
+
+### 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
+
+<DatePicker locale="no" dateFormat="d/m/Y" datePickerType="single">
+  <DatePickerInput placeholder="dd/mm/yyyy" />
+</DatePicker>
+
+```jsx
+// Load Norwegian text with the proper date format
+<DatePicker locale="no" dateFormat="d/m/Y" datePickerType="single">
+  <DatePickerInput placeholder="dd/mm/yyyy" />
+</DatePicker>
+```
+
+### 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.
+
+<DatePicker maxDate="09/01/2020" datePickerType="single">
+  <DatePickerInput placeholder="dd/mm/yyyy" />
+</DatePicker>
+<br />
+<DatePicker
+  maxDate="09/01/2020"
+  datePickerType="single"
+  locale="no"
+  dateFormat="d/m/Y">
+  <DatePickerInput placeholder="mm/dd/yyyy" />
+</DatePicker>
+
+```jsx
+<DatePicker maxDate="09/01/2020">
+  <DatePickerInput placeholder="mm/dd/yyyy" />
+</DatePicker>
+
+<DatePicker
+  maxDate="09/01/2020"
+  datePickerType="single"
+  locale="no"
+  dateFormat="d/m/Y">
+  <DatePickerInput placeholder="mm/dd/yyyy" />
+</DatePicker>;
+```
+
+### DatePicker `minDate`
+
+Works similarly to the `maxDate` prop. [See above](#datepicker-maxdate).
+
+<DatePicker maxDate="09/01/2020" datePickerType="single" value="07/15/1988">
+  <DatePickerInput placeholder="dd/mm/yyyy" />
+</DatePicker>
+
+### 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.
+
+<DatePicker maxDate="09/01/2020" datePickerType="single" value="07/15/1988">
+  <DatePickerInput placeholder="dd/mm/yyyy" />
+</DatePicker>
+<br />
+<DatePicker
+  maxDate="09/01/2020"
+  datePickerType="single"
+  value={new Date().setDate(-10)}>
+  <DatePickerInput placeholder="dd/mm/yyyy" />
+</DatePicker>
+
+```jsx
+<DatePicker maxDate="09/01/2020" datePickerType="single" value="07/15/1988">
+  <DatePickerInput placeholder="dd/mm/yyyy" />
+</DatePicker>
+
+<DatePicker
+  maxDate="09/01/2020"
+  datePickerType="single"
+  value={new Date().setDate(-10)}>
+  <DatePickerInput placeholder="dd/mm/yyyy" />
+</DatePicker>
+```
+
 ## References
 
 ## Feedback