@nypl/design-system-react-components 1.0.0 → 1.0.3-beta

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

@@ -1,452 +0,0 @@
-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;
-};
-```