@nypl/design-system-react-components 0.23.4 → 0.25.1

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

@@ -0,0 +1,284 @@
+import {
+  Meta,
+  Story,
+  Canvas,
+  ArgsTable,
+  Preview,
+  Description,
+} from "@storybook/addon-docs/blocks";
+import { withDesign } from "storybook-addon-designs";
+import { getCategory } from "../../utils/componentCategories";
+
+import DatePicker from "./DatePicker";
+import { DatePickerTypes } from "./DatePickerTypes";
+
+<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={{
+    blockName: { table: { disable: true } },
+    className: { table: { disable: true } },
+    modifiers: { table: { disable: true } },
+    id: { table: { disable: true } },
+    nameTo: { table: { disable: true } },
+    nameFrom: { table: { disable: true } },
+    value: { table: { disable: true } },
+    refTo: { table: { disable: true } },
+  }}
+/>
+
+# DatePicker
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.24.0`   |
+| Latest            | `0.24.0`   |
+
+<Description of={DatePicker} />
+
+<Canvas withToolbar>
+  <Story
+    name="DatePicker"
+    args={{
+      dateType: DatePickerTypes.Full,
+      dateFormat: "yyyy-MM-dd",
+      dateRange: false,
+      initialDate: "1/1/2021",
+      minDate: "1/1/2021",
+      maxDate: "1/1/2022",
+      nameFrom: "visit-dates",
+      labelText: "Select the date you want to visit NYPL",
+      helperText: "Note that the Library may be closed on Sundays.",
+      helperTextFrom: "Select start date.",
+      helperTextTo: "Select end date.",
+      invalidText: "Please select a valid date.",
+      showLabel: true,
+      errored: false,
+      disabled: false,
+      required: false,
+      showOptReqLabel: true,
+    }}
+  >
+    {(args) => <DatePicker id="visit-dates" {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="DatePicker" />
+
+## Date Range
+
+A date range can be rendered by setting the `dateRange` prop to `true`. This
+will render two input fields with labels "From" and "To". If the component has
+an error, or if this is a required field, 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/2021" and the max date
+is "1/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"
+      dateType={DatePickerTypes.Full}
+      dateFormat="yyyy-MM-dd"
+      dateRange={true}
+      minDate="1/1/2021"
+      maxDate="1/1/2022"
+      labelText="Select the date range you want to visit NYPL"
+      nameFrom="visit-dates"
+      helperTextFrom="From this date."
+      helperTextTo="To this date."
+      helperText="Select a valid date range."
+      invalidText="Please select a valid date range."
+      showOptReqLabel={false}
+    />
+  </Story>
+</Canvas>
+
+## 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 `DatePickerTypes.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={DatePickerTypes.Month}
+      dateRange={false}
+      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
+`DatePickerTypes.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="month-date"
+      dateType={DatePickerTypes.Year}
+      dateRange={false}
+      labelText="Select the year you want to visit NYPL"
+      helperText="Note that the Library may be closed on Sundays."
+      showOptReqLabel={false}
+    />
+  </Story>
+</Canvas>
+
+## Other States
+
+### Errored State
+
+<DatePicker
+  id="month-date"
+  dateType={DatePickerTypes.Full}
+  dateRange={true}
+  labelText="Select the year you want to visit NYPL"
+  helperText="Note that the Library may be closed on Sundays."
+  invalidText="Please select a valid year."
+  errored={true}
+  showOptReqLabel={false}
+/>
+<br />
+
+### Disabled State
+
+<DatePicker
+  id="month-date"
+  dateType={DatePickerTypes.Full}
+  dateRange={true}
+  labelText="Select the year you want to visit NYPL"
+  disabled={true}
+  showOptReqLabel={false}
+/>
+
+## Getting Date Data Values
+
+### Controlled Component Using `onChange` prop
+
+If your application uses controlled React components and the 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.
+
+```jsx
+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={DatePickerTypes.Full}
+  dateRange={true}
+  labelText="Select the date range you want to visit NYPL"
+  invalidText="Please select a valid date range."
+  onChange={onChange}
+/>;
+```
+
+### 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.
+
+```jsx
+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={DatePickerTypes.Full}
+    dateRange={true}
+    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()}
+  />
+</form>;
+```
+
+The above is specific to `react-hook-form` but a similar pattern can be used
+with normal React `ref` values.
+
+```jsx
+const refStart = React.createRef<TextInputRefType>();
+const refEnd = React.createRef<TextInputRefType>();
+// ...
+<DatePicker
+  id="date-range"
+  dateType={DatePickerTypes.Full}
+  dateRange={true}
+  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}
+/>
+
+// ...
+// Get the value through:
+const onSubmit = () => {
+  // ...
+  const startDate = refStart.current.value;
+  const endDate = refEnd.current.value;
+};
+```