npm package: @highlight-ui/date-time-picker
Description: Date and Time Picker components for Highlight UI library
Author: Personio GmbH & Co. KG
Latest version: 8.13.0

[![npm](https://img.shields.io/npm/v/@highlight-ui/date-time-picker)](https://www.npmjs.com/package/@highlight-ui/date-time-picker)
[![personio.design](https://img.shields.io/static/v1?label=Personio&message=zeroheight&color=yellow)](https://www.personio.design/40d648a47/v/0/p/332388-date-and-time-picker/b/583bbd)
[![storybook.personio.design](https://img.shields.io/static/v1?label=Personio&message=storybook&color=red)](https://storybook.personio.design/?path=/story/forms-and-input-date-and-time-pickers-datepicker--basic-date-picker)

# @highlight-ui/date-time-picker

## Installation

Using npm:

```bash
npm install @highlight-ui/date-time-picker @highlight-ui/i18n@^2.0.4 flatpickr@^4.6
```

Using yarn:

```bash
yarn add @highlight-ui/date-time-picker @highlight-ui/i18n@^2.0.4 flatpickr@^4.6
```

Using pnpm:

```bash
pnpm install @highlight-ui/date-time-picker @highlight-ui/i18n@^2.0.4 flatpickr@^4.6
```

In your (S)CSS file:

```scss
@import url('@highlight-ui/date-time-picker');
```

Once the package is installed, you can import the library:

```ts
import {
  DatePicker,
  TimePicker,
  RangeDatePicker,
} from '@highlight-ui/date-time-picker';
```

## Usage

### DatePicker

```tsx
import React, { useState } from 'react';
import { DatePicker } from '@highlight-ui/date-time-picker';

export default function DateTimePickerExample() {
  return (
    <DatePicker
      value={selectedDate}
      onChange={(date, asStr) => {
        console.log(date, asStr);
      }}
      onBlur={(e) => {
        console.log(e);
      }}
      {...props}
    />
  );
}
```

### RangeDatePicker

```tsx
import React, { useState } from 'react';
import { RangeDatePicker } from '@highlight-ui/date-time-picker';

export default function RangeDatePickerExample() {
  return (
    <RangeDatePicker
      range={range}
      onChange={(dates, strings) => {
        console.log(dates, strings);
      }}
    />
  );
}
```

### TimePicker

```tsx
import React, { useState } from 'react';
import { TimePicker } from '@highlight-ui/date-time-picker';

export default function TimePickerExample() {
  return (
    <TimePicker
      value={selectedValue}
      onChange={(time, asStr) => {
        console.log(dates, strings);
      }}
  );
}
```

## Props 📜

### DatePicker

> All props are based on the [`DateInputProps`](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/date-time-picker/src/types.tsx?ref_type=heads#L33)

| Prop            | Type                                         | Required | Default | Description                                                                                       |
| :-------------- | :------------------------------------------- | :------- | :------ | :------------------------------------------------------------------------------------------------ |
| `className`     | `string`                                     | No       |         | Allows providing a custom class name to the DIV element that surrounds the text                   |
| `onChange`      | `(date?: Date, inputValue?: string) => void` | No       |         | The callback being fired on each change on the input or when a date from the calendar is selected |
| `closeOnSelect` | `boolean`                                    | No       | `false` | Should the calendar close after each selection                                                    |
| `noCalendar`    | `boolean`                                    | No       | `false` | Should it show the calendar element when the input has focus                                      |

### RangeDatePicker

> All props are based on the [`DateInputProps`](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/date-time-picker/src/types.tsx?ref_type=heads#L33)

| Prop            | Type                                                                                                                                                         | Required | Default | Description                                                                                                   |
| :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------ |
| `className`     | `string`                                                                                                                                                     | No       |         | Allows providing a custom class name to the DIV element that surrounds the text                               |
| `range`         | [`DateRange`](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/date-time-picker/src/types.tsx?ref_type=heads#L6) | No       |         | The controlled value of the input                                                                             |
| `onChange`      | `(date?: Date, inputValue?: string) => void`                                                                                                                 | No       |         | The callback being fired on each change on the inputs or when a range of dates from the calendar are selected |
| `closeOnSelect` | `boolean`                                                                                                                                                    | No       | `false` | Should the calendar close after each selection                                                                |
| `startInputId`  | `string`                                                                                                                                                     | No       |         | This value will be passed as id for the start range input                                                     |
| `endInputId`    | `string`                                                                                                                                                     | No       |         | This value will be passed as id for the end range input                                                       |

### TimePicker

> All props are based on the [`TimePickerInputProps`](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/date-time-picker/src/types.tsx?ref_type=heads#L83)

| Prop           | Type                                                                                                                                       | Required | Default                                                                   | Description                                                                                                                                                                           |
| :------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `defaultValue` | `Date`                                                                                                                                     | No       |                                                                           | If `defaultValue` is `Date` or `null` TimePicker act as uncontrolled ignoring `value` prop                                                                                            |
| `day`          | `Date`                                                                                                                                     |          | Day that should be returned in the `onChange` handler along with the time |
| `onChange`     | `(date?: Date, inputValue?: string) => void`                                                                                               | No       |                                                                           | The callback being fired on each change on the input or when a preset time is selected                                                                                                |
| `presetTimes`  | `Date[]`                                                                                                                                   | No       |                                                                           | An array of time options from which the user can choose                                                                                                                               |
| `value`        | `Date`                                                                                                                                     | No       |                                                                           | The controlled value of the input                                                                                                                                                     |
| `onBlur`       | `(e: React.FocusEvent) => void`                                                                                                            | No       |                                                                           | This callback being fired on each blur event                                                                                                                                          |
| `maskOptions`  | [`MaskOptions`](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/blob/master/packages/ui/input/src/imaskExports.ts#L3) | No       |                                                                           | Function which accepts locale and returns an [imaskjs](https://imask.js.org/guide.html) configuration object used for creating an IMask instance which will control the input element |

## Keyboard Navigation ⌨️

Here are the keyboard shortcuts to help navigate through the date picker. These keys allow for smooth accessibility and interaction with the calendar:

### General Navigation
| Key (Mac Shortcut)     | Function                                                                                              |
|------------------------|-------------------------------------------------------------------------------------------------------|
| `Tab` (`Tab`)          | Focus on month navigation components (arrows, trigger and 'Today' button)               |
| `Escape` (`Escape`)    | Close the calendar and return focus to the calendar icon.                                             |
| `Space`, `Enter`       | Opens the calendar when the icon is focused.                                                        |

### Within Calendar
| Key (Mac Shortcut)     | Function                                                                                              |
|------------------------|-------------------------------------------------------------------------------------------------------|
| `Home` (`fn` + `←`)    | Focus on the first day of the current week.                                                           |
| `End` (`fn` + `→`)     | Focus on the last day of the current week.                                                            |
| `PageUp` (`fn` + `↑`)  | Navigate to the previous month. `Shift` + `PageUp` navigates to the same month in the previous year.   |
| `PageDown` (`fn` + `↓`)| Navigate to the next month. `Shift` + `PageDown` navigates to the same month in the next year.         |
| `Up Arrow` (`↑`)       | Move to the same day of the previous week. If at top edge, move to previous month.                     |
| `Down Arrow` (`↓`)     | Move to the same day of the next week. If at bottom edge, move to next month.                         |
| `Right Arrow` (`→`)    | Move to the next day. If at right edge, move to the next month.                                       |
| `Left Arrow` (`←`)     | Move to the previous day. If at left edge, move to the previous month.                                 |

Note: When the calendar is blurred, the focus returns to the calendar icon. This happens when pressing the `Escape` key. The `Tab` key will move focus to the next element in the focus tree.


## Contributing 🖌️

Please visit [personio.design](https://www.personio.design/40d648a47/v/0/p/332388-date-and-time-picker/b/583bbd) for usage guidelines and visual examples.

If you're interested in contributing, please visit our [contribution page](https://www.personio.design/40d648a47/v/0/p/138faf-about-the-process).