cunningham/packages/react/src/components/Forms/DatePicker/index.mdx

import { Canvas, Meta, Story, Source, ArgsTable } from '@storybook/addon-docs';
import { DatePicker } from "./index";
import { DateRangePicker } from "./index";

<Meta title="Components/Forms/DatePicker/Doc" component={DatePicker}/>


# DatePicker


Cunningham provides a versatile DatePicker component to select or input a date in your form. It uses the headless
UI components provided by [React-Spectrum](https://react-spectrum.adobe.com/react-aria/useDatePicker.html) from Adobe.

> Time features will be available soon.


## Basic

<Source
  language='ts'
  dark
  format={false}
  code={`
  <DatePicker label="Pick a date" />
  `}
/>

<Canvas>
  <Story id="components-forms-datepicker--default"/>
</Canvas>

## Default value
You can use the following props to change the default value of the DatePicker component by using the `state` props.

<Canvas sourceState="shown">
  <Story id="components-forms-datepicker--default-value"/>
</Canvas>

## Range

<Source
  language='ts'
  dark
  format={false}
  code={`
  <DateRangePicker startLabel="Start date" endLabel="Due date" name="datepicker" />
  `}
/>

When using it within a form, you'll access its values using separate inputs for the start and end values. The start input's
name will be the `DateRangePicker`'s name suffixed by `_start` and the end input's name will be the `DateRangePicker`'s name suffixed by `_end`.
Ex: If a `DateRangePicker` is named `"subscription"`, you would access its values as follow:

<Source
  language='ts'
  dark
  format={false}
  code={`

  formData = {
    datepickerStart: data.get("subscription_start"),
    datepickerEnd: data.get("subscription_end"),
  };
  `}
/>

<Canvas>
  <Story id="components-forms-datepicker--range-default"/>
</Canvas>


## States

You can use the following props to change the state of the DatePicker component by using the `state` props.

<Canvas sourceState="shown">
  <Story id="components-forms-datepicker--error"/>
  <Story id="components-forms-datepicker--success"/>
</Canvas>

## Disabled

As a regular input, you can disable it by using the `disabled` props.

<Canvas sourceState="shown">
  <Story id="components-forms-datepicker--disabled"/>
  <Story id="components-forms-datepicker--disabled-value"/>
</Canvas>

## Texts

As the component uses [Field](?path=/story/components-forms-field-doc--page), you can use the `text` props to provide a description of the checkbox.

<Canvas sourceState="shown">
  <Story id="components-forms-datepicker--with-text"/>
</Canvas>

## Controlled / Non Controlled

Like a native input, you can use the DatePicker component in a controlled or non controlled way. You can see the example below
using the component in a controlled way.

<Canvas sourceState="shown">
  <Story id="components-forms-datepicker--controlled"/>
  <Story id="components-forms-datepicker--range-controlled"/>
</Canvas>

## MinValue / MaxValue

You can pass a date range that are valid using the `minValue` and `maxValue` props.

<Canvas sourceState="shown">
  <Story id="components-forms-datepicker--min-max-value"/>
</Canvas>

## Invalid date

When passing an invalid date, for example outside of the valid range, the DatePicker component would render invalid.

<Canvas sourceState="shown">
  <Story id="components-forms-datepicker--invalid-value"/>
</Canvas>

## International calendars

When passing a locale value to the DatePicker components, dates would be automatically displayed in the appropriate calendar system.
By default, the DatePicker component uses the CunninghamProvider locale.

<Canvas sourceState="shown">
  <Story id="components-forms-datepicker--custom-locale"/>
  <Story id="components-forms-datepicker--cunningham-locale"/>
</Canvas>

## Timezone management

By default, the component uses the user's local timezone. When a timezone is passed, dates are selected at midnight in that specific timezone.
If a value or default value is provided, the component preserves the time unless the user clears the input.
When the input is cleared, the dates are reset to midnight in the current timezone.
The component accepts both UTC date-time strings and date-time strings with offsets from UTC.
However, it consistently returns the output in UTC time, ensuring uniformity across different timezone.


## Props

You can see the list of props below.

### DatePicker

<ArgsTable of={DatePicker} />

### DateRangePicker

<ArgsTable of={DateRangePicker} />


## Design tokens

Here are the custom design tokens defined by the datepicker.

| Token        	| Description                 	|
|---------------	|-----------------------------	|
| background-color   	| Background color of the datepicker    	|
| border-color   	| Border color of the datepicker    	|
| border-color--hover   	| Border color of the datepicker on mouse hover   	|
| border-color--focus   	| Border color of the datepicker when focus   	|
| border-radius     	| Border radius of the datepicker      	|
| border-width     	| Border width of the datepicker      	|
| border-radius--hover   	| Border radius of the datepicker on mouse hover    	|
| border-radius--focus   	| Border radius of the datepicker when focused    	|
| color   	| Value color  	|
| font-size        	| Value font size        	|
| height | Height of the combo box |
| item-background-color--hover | Background color of the item on mouse hover (months/years menus)   	|
| item-background-color--selected | Background color of the selected item (months/years menus)   	|
| item-color | Color of the item (months/years menus)    	|
| item-font-size | Font size of the item (months/years menus)    	|
| menu-background-color | Background color of the menu (months/years menus)    	|
| grid-cell--border-color--today | Border color of the today grid-cell    	|
| grid-cell--color--today | Value color of the today grid-cell    	|
| range-selection-background-color | Value color of the selected grid-cells    	|

See also [Field](?path=/story/components-forms-field-doc--page)