# Input Date

InputDate provides a multi-modal way for the user to select a date, using
either:

* Form Field
* Visual calendar selector and comes complete with the ability to re-format user
  input into an expected date format.

## Design & usage guidelines

The InputDate should be used in most cases where the user needs to select a
date.

### States

#### Disabled

```tsx
import React from "react";
import { InputDate } from "@jobber/components/InputDate";
import type { InputDateProps } from "@jobber/components/InputDate";

export function InputDateDisabledExample(props: InputDateProps) {
  return <InputDate placeholder="Start Date" disabled={true} {...props} />;
}
```

#### Invalid

```tsx
import React from "react";
import type { InputDateProps } from "@jobber/components/InputDate";
import { InputDate } from "@jobber/components/InputDate";

export function InputDateInvalidExample(props: InputDateProps) {
  return (
    <InputDate
      placeholder="Start date"
      error="Start Date is required"
      invalid={true}
      {...props}
    />
  );
}
```

## Content guidelines

The InputDate should only be used to display and submit date values. For other
input usage, see [Related Components](#component-view-related-components).

## Responsiveness

When the InputDate is near the top or bottom of the viewport, the Datepicker
will adjust its position to remain in view.

The FormField for InputDate will take up the full available width of its parent.
If used in an [InputGroup](/components/InputGroup), it will take up the
available amount of space left by any other inputs in the group.

## Related components

* On web if you do not need an accompanying form field, you can use the
  [DatePicker](/components/DatePicker) on its own
* If you need to allow the user to enter time, use
  [InputTime](../InputTime/InputTime.md)
* If you just need a text input, use [InputText](../InputText/InputText.md)

## Accessibility

Accessibility concerns for the InputDate are captured by:

### FormField

Provides a label, announces input type, can be focused, and handles error
validation and messaging.

### Datepicker

[Datepicker](/components/DatePicker) is keyboard-operable and announces the
currently-focused date available for selection to the user via assistive
technology.


## Developer notes

Some functionality that we have opted not to introduce at this time, but that
would be relatively feasible to add in the future:

* allow for the concept of a date-range selection
* allow for certain days or dates to be excluded from selection

### Web

InputDate pairs with the

AtlantisContext

using the provided `firstDayOfWeek` value to determine what day the calendar date
picking UI will use to start weeks.

To leverage this behavior, implement the

AtlantisContext

at the root of the application, populated with the applicable value.


## Props

### Mobile

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `accessibilityHint` | `string` | No | — | Helps users understand what will happen when they perform an action |
| `accessibilityLabel` | `string` | No | — | VoiceOver will read this string when a user selects the element |
| `clearable` | `"always" | "never"` | No | — | Defaulted to "always" so user can clear the dates whenever there's a value. |
| `defaultValue` | `Date` | No | — | The initial value for the input. |
| `disabled` | `boolean` | No | — | Disable the input |
| `emptyValueLabel` | `string` | No | — | This label is shown to the user when there's no selected date. |
| `invalid` | `boolean | string` | No | — | Highlights the field red and shows message below (if string) to indicate an error |
| `maxDate` | `Date` | No | — | Maximum date the user can set. |
| `minDate` | `Date` | No | — | Minimum date the user can set |
| `name` | `string` | No | — | Adding a `name` would make this component "Form controlled" and must be nested within a `<Form />` component.  Cannot... |
| `onChange` | `((value?: Date) => void) | ((value?: Date) => void)` | No | — | The callback that fires whenever a date gets selected. |
| `placeholder` | `string` | No | — | Hint text that goes above the value once the field is filled out |
| `showMiniLabel` | `boolean` | No | `true` | Controls the visibility of the mini label that appears inside the input when a value is entered. By default, the plac... |
| `validations` | `Omit<RegisterOptions<FieldValues, string>, "disabled" | "setValueAs" | "valueAsNumber" | "valueAsDate">` | No | — | Shows an error message below the field and highlights it red when the value is invalid. Only applies when nested with... |
| `value` | `Date | string` | No | — | The value shown on the field. This gets automatically formatted to the account's date format.  Cannot be declared if ... |