@nypl/design-system-react-components 1.0.1 → 1.0.2

package/src/components/DatePicker/DatePicker.stories.mdx

@@ -0,0 +1,452 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import DatePicker from "./DatePicker";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("DatePicker")}
+  component={DatePicker}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=11689%3A0",
+    },
+    jest: ["DatePicker.test.tsx"],
+  }}
+  argTypes={{
+    className: { control: false },
+    dateFormat: {
+      table: { defaultValue: { summary: "yyyy-MM-dd" } },
+    },
+    dateType: {
+      control: { type: "select" },
+      table: { defaultValue: { summary: "full" } },
+    },
+    id: { control: false },
+    isDateRange: {
+      table: { defaultValue: { summary: false } },
+    },
+    isDisabled: {
+      table: { defaultValue: { summary: false } },
+    },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    key: { table: { disable: true } },
+    labelText: {
+      table: { defaultValue: { summary: "From" } },
+    },
+    nameFrom: { control: false },
+    nameTo: { control: false },
+    onChange: { control: false },
+    ref: { table: { disable: true } },
+    refTo: { control: false },
+    showHelperInvalidText: {
+      table: { defaultValue: { summary: true } },
+    },
+    showLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    showRequiredLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+  }}
+/>
+
+# DatePicker
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.24.0`   |
+| Latest            | `0.28.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Date Range](#date-range)
+- [Calendar Types](#calendar-types)
+- [Other States](#other-states)
+- [Date Inputs and Output](#date-inputs-and-output)
+- [Getting Date Input Values](#getting-date-input-values)
+
+## Overview
+
+<Description of={DatePicker} />
+
+This is fully customizable to allow selectable full dates, only the month, or
+only they year as input. Initial date values and max and min date values can
+also be added through props.
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="DatePicker with Controls"
+    args={{
+      className: undefined,
+      dateFormat: "yyyy-MM-dd",
+      dateType: "full",
+      helperText: "Note that the Library may be closed on Sundays.",
+      helperTextFrom: "Select start date.",
+      helperTextTo: "Select end date.",
+      id: "datePicker-id",
+      initialDate: "4/1/2022",
+      initialDateTo: "12/1/2022",
+      invalidText: "Please select a valid date.",
+      isDateRange: false,
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+      labelText: "Select the date you want to visit NYPL",
+      maxDate: "1/1/2023",
+      minDate: "1/1/2022",
+      nameFrom: "visit-dates-from",
+      nameTo: "visit-dates-to",
+      onChange: undefined,
+      refTo: undefined,
+      showHelperInvalidText: true,
+      showLabel: true,
+      showRequiredLabel: true,
+    }}
+  >
+    {(args) => <DatePicker {...args} onChange={undefined} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="DatePicker with Controls" />
+
+## Accessibility
+
+The Reservoir `DatePicker` component implements the `react-datepicker` npm package.
+This package exports a component that is used internally to display the popup
+calendar, manage its data, and associate the `<label>` element with its corresponding
+`<input>` element. This component is accessible through keyboard navigation.
+
+The Reservoir `DatePicker` handles the grouping of the two `<input>` elements in
+the "date range" mode by wrapping the elements in a `<fieldset>` element with
+its own `<legend>` label for the group. Note that this is in addition to the two
+labels that each `<input>` element is associated with.
+
+When `showLabel` is set to false, the single `<input>` element's `aria-label`
+attribute is set to the required `labelText` value. In the "date range" mode,
+when `showLabel` is set to false, the `<fieldset>`'s `<legend>` will have the
+`labelText` visually hidden.
+
+Resources:
+
+- [react-datepicker Accessibility](https://github.com/Hacker0x01/react-datepicker#accessibility)
+
+## Date Range
+
+A date range can be rendered by setting the `isDateRange` prop to `true`. This
+will render two input fields with labels "From" and "To". If the component has
+an error, has required fields, or if it is disabled, then both input elements
+will share the props and styling. Note that for date range types, a `fieldset`
+is used as the parent wrapper and the `labelText` is used for the `legend`
+element text.
+
+Note: In the following example, the minimum date is "1/1/2022" and the max date
+is "7/1/22". This means only values within this range are selectable from the
+popup calendar.
+
+<Canvas withToolbar>
+  <Story name="Date Range">
+    <DatePicker
+      id="date-range"
+      dateFormat="yyyy-MM-dd"
+      dateType="full"
+      minDate="1/1/2022"
+      maxDate="7/1/2022"
+      labelText="Select the date range you want to visit NYPL"
+      nameFrom="visit-dates-from"
+      nameTo="visit-dates-to"
+      helperTextFrom="From this date."
+      helperTextTo="To this date."
+      helperText="Select a valid date range."
+      invalidText="There was an error with the date range :("
+      isDateRange
+    />
+  </Story>
+</Canvas>
+
+## Calendar Types
+
+### Full Date Input
+
+By default, the `DatePicker` will display the input date value in the full
+format that contains the year, month, and day such as "2021-01-30". Although
+this is the default, it can be explicitly set through the `dateType` prop with
+value of `"full"`.
+
+### Month Date Input
+
+It's possible to select dates by skipping the day value and only selecting
+the month and the year when `dateType` is set to `"month"`. Note
+that all 12 months will appear in the popup calendar with their abbreviated names.
+
+<Canvas withToolbar>
+  <Story name="Month Date Input">
+    <DatePicker
+      id="month-date"
+      dateType="month"
+      labelText="Select the month you want to visit NYPL"
+      helperText="Note that the Library may be closed on Sundays."
+      invalidText="Please select a valid month."
+    />
+  </Story>
+</Canvas>
+
+### Year Date Input
+
+It's possible to select dates by only the year when `dateType` is set to
+`"year"`. Note that only 12 values will appear in the popup calendar; the four
+previous years, the current year, and the next seven years.
+
+<Canvas withToolbar>
+  <Story name="Year Date Input">
+    <DatePicker
+      id="year-date"
+      dateType="year"
+      labelText="Select the year you want to visit NYPL"
+      helperText="Note that the Library may be closed on Sundays."
+    />
+  </Story>
+</Canvas>
+
+## Other States
+
+### Errored State
+
+<Canvas>
+  <DSProvider>
+    <DatePicker
+      id="invalid-date"
+      dateType="full"
+      labelText="Select the year you want to visit NYPL"
+      helperText="Note that the Library may be closed on Sundays."
+      invalidText="Please select a valid date."
+      isInvalid
+      isDateRange
+    />
+  </DSProvider>
+</Canvas>
+
+### Disabled State
+
+<Canvas>
+  <DSProvider>
+    <DatePicker
+      id="disabled-date"
+      dateType="full"
+      labelText="Select the year you want to visit NYPL"
+      isDateRange
+      isDisabled
+    />
+  </DSProvider>
+</Canvas>
+
+### Required State
+
+The "Required" text in the legend in the date range, or the label in a normal
+date input, can be hidden when `showRequiredLabel` is set to `false`.
+
+<Canvas>
+  <DSProvider>
+    <DatePicker
+      id="required-date"
+      dateType="full"
+      labelText="Select the year you want to visit NYPL"
+      isDateRange
+      isRequired
+    />
+  </DSProvider>
+</Canvas>
+
+## Date Inputs and Output
+
+### Initial Date Values
+
+The initial date values can be set through `initialDate` for the "From" input
+field and `initialDateTo` for the "To" input field. In the following examples,
+`initialDate` is `"12/1/21"` and `initialDateTo` is `"12/10/21"`. The
+`initialDate` and `initialDateTo` values are used in the JS `Date` function so
+they needs to be in that specific format. Note that according to the NYPL
+styleguide, we display dates as "year-month-day" by default.
+
+<Canvas>
+  <DSProvider>
+    <DatePicker
+      id="init-dates"
+      dateType="full"
+      labelText="Select the date you want to visit NYPL"
+      initialDate="12/1/21"
+      initialDateTo="12/10/21"
+      isDateRange
+    />
+  </DSProvider>
+</Canvas>
+
+### Date Format
+
+The display date format can be updated through the `dateFormat` prop. The
+default is set to `"yyyy-MM-dd"` based on the NYPL styleguide. This should be
+written in [ISO-8601 format](https://www.w3.org/TR/NOTE-datetime).
+
+<Canvas>
+  <DSProvider>
+    <DatePicker
+      id="format-date"
+      dateFormat="MM-dd-yyyy"
+      dateType="full"
+      labelText="Select the date you want to visit NYPL"
+      initialDate="12/1/21"
+      initialDateTo="12/10/21"
+      isDateRange
+    />
+  </DSProvider>
+</Canvas>
+
+### Max and Min Date Values
+
+The maximum and minimum date values can be set through the `maxDate` and
+`minDate` props, respectively. In this example, go back to January through
+February to see the dates that are available to select in 2022.
+
+<Canvas>
+  <DSProvider>
+    <DatePicker
+      id="max-min-dates"
+      dateFormat="MM-dd-yyyy"
+      dateType="full"
+      labelText="Select the date you want to visit NYPL"
+      minDate="1/1/2022"
+      maxDate="3/1/2022"
+      isDateRange
+    />
+  </DSProvider>
+</Canvas>
+
+## Getting Date Input Values
+
+### Controlled Component Using `onChange` prop
+
+If your application uses controlled React components and the Reservoir Design
+System (DS) DatePicker must be controlled, you can extract the data through the
+`onChange` prop function. This will be called every time the date is updated in
+either the start date input field or the end date input field. The returned
+data is an object with `startDate` and `endDate` keys and `Date` object values.
+
+```tsx
+const onChange = (data) => {
+  // This will return an object such as:
+  // {
+  //   startDate: dateValue,
+  //   endDate: dateValue
+  // }
+  // Note that `dateValue` is a `Date` object so you need to get the date value
+  // yourself. The `endDate` attribute will only appear if the DS DatePicker
+  // component is a date range.
+  console.log(data);
+};
+// ...
+
+// Example of the DS DatePicker instance with the function above:
+<DatePicker
+  id="date-range"
+  dateType="full"
+  labelText="Select the date range you want to visit NYPL"
+  invalidText="Please select a valid date range."
+  onChange={onChange}
+  isDateRange
+/>;
+```
+
+### Uncontrolled Component Using `ref`s
+
+If your application uses uncontrolled components, you can pass React `ref` props
+to the DS DatePicker component to get values from the DOM. In this scenario, you
+need to also pass in a `nameFrom` prop so that the `ref` values knows what DOM
+element to get the value from. If you are using a date range, you need to pass
+additional `nameTo` and `refTo` props or else only the start date value will be
+obtained.
+
+The following example is using the `register` React `ref` from the
+`react-hook-form` package.
+
+```tsx
+import { useFormContext } from "react-hook-form";
+// ...
+const { register, handleSubmit } = useFormContext();
+// ...
+const submitForm = (formData) => {
+  // This will return an object with all the DOM element values that were
+  // registered with a `name` attribute.
+  // Note that the returned values are strings and NOT Date objects.
+  // {
+  //   visitDateFrom: "2020-01-01"
+  //   visitDateTo: "2021-01-01"
+  // }
+  console.log(formData);
+  // ...
+};
+
+<form
+  onSubmit={handleSubmit(submitForm)}
+  method="post"
+  action="/some/api/endpoint"
+>
+  <DatePicker
+    id="date-range"
+    dateType="full"
+    labelText="Select the date range you want to visit NYPL"
+    nameFrom="visitDateFrom"
+    nameTo="visitDateTo"
+    invalidText="Please select a valid date range."
+    ref={register()}
+    refTo={register()}
+    isDateRange
+  />
+</form>;
+```
+
+The above is specific to `react-hook-form` but a similar pattern can be used
+with normal React `ref` values.
+
+```tsx
+const refStart = React.createRef<TextInputRefType>();
+const refEnd = React.createRef<TextInputRefType>();
+// ...
+<DatePicker
+  id="date-range"
+  dateType="full"
+  labelText="Select the date range you want to visit NYPL"
+  nameFrom="visitDateFrom"
+  nameTo="visitDateTo"
+  invalidText="Please select a valid date range."
+  ref={refStart}
+  refTo={refEnd}
+  isDateRange
+/>;
+
+// ...
+// Get the value through:
+const onSubmit = () => {
+  // ...
+  const startDate = refStart.current.value;
+  const endDate = refEnd.current.value;
+};
+```