# 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](../InputGroup/InputGroup.md), 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](../Datepicker/Datepicker.md) 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](../Datepicker/Datepicker.md) 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

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onChange` | `(newValue: Date, event?: ChangeEvent<HTMLInputElement>) => void` | Yes | — | Callback for value changes. @param newValue - The new Date value @param event - Optional change event |
| `align` | `"center" | "right"` | No | — | Determines the alignment of the text inside the input. |
| `aria-activedescendant` | `string` | No | — | ID of the currently active descendant element. Used for composite widgets like combobox or listbox. @see {@link https... |
| `aria-autocomplete` | `"both" | "inline" | "list" | "none"` | No | — | Indicates the type of autocomplete interaction. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-autocomplete} |
| `aria-controls` | `string` | No | — | Indicates the element that controls the current element. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-controls} |
| `aria-describedby` | `string` | No | — | Identifies the element (or elements) that describes the object. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-... |
| `aria-details` | `string` | No | — | Identifies the element (or elements) that provide a detailed, extended description. @see {@link https://www.w3.org/TR... |
| `aria-expanded` | `Booleanish` | No | — | Indicates whether the element is expanded or collapsed. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-expanded} |
| `aria-label` | `string` | No | — | Defines a string value that labels the current element. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-label} |
| `aria-labelledby` | `string` | No | — | Identifies the element (or elements) that labels the current element. @see {@link https://www.w3.org/TR/wai-aria-1.2/... |
| `aria-required` | `Booleanish` | No | — | Indicates that user input is required before form submission. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-re... |
| `autoComplete` | `string` | No | — | Autocomplete behavior for the input (React casing, string values only). Use standard HTML autocomplete values or "on"... |
| `autoFocus` | `boolean` | No | — | Whether the input should be auto-focused (React casing). |
| `description` | `ReactNode` | No | — | Further description of the input, can be used for a hint. |
| `disabled` | `boolean` | No | — | Whether the input is disabled. |
| `emptyValueLabel` | `string` | No | — | Text to display instead of a date value |
| `error` | `string` | No | — | Error message to display. This also highlights the field red. |
| `id` | `string` | No | — | The unique identifier for the input element. |
| `inline` | `boolean` | No | — | Adjusts the form field to go inline with content. |
| `inputMode` | `"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"` | No | — | Input mode hint for virtual keyboards. |
| `invalid` | `boolean` | No | — | Highlights the field red to indicate an error. |
| `loading` | `boolean` | No | — | Show a spinner to indicate loading. |
| `maxDate` | `Date` | No | — | The maximum selectable date. |
| `minDate` | `Date` | No | — | The minimum selectable date. |
| `name` | `string` | No | — | The name attribute for the input element. |
| `onBlur` | `(event: FocusEvent<HTMLInputElement | HTMLTextAreaElement, Element>) => void` | No | — | Blur event handler. |
| `onEnter` | `(event: KeyboardEvent<Element>) => void` | No | — | @deprecated Use `onKeyDown` or `onKeyUp` instead. |
| `onFocus` | `(event: FocusEvent<HTMLInputElement | HTMLTextAreaElement, Element>) => void` | No | — | Focus event handler. |
| `onKeyDown` | `(event: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void` | No | — | Key down event handler. |
| `onKeyUp` | `(event: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void` | No | — | Key up event handler. |
| `pattern` | `string` | No | — | Validation pattern (regex) for the input. |
| `placeholder` | `string` | No | — | Text that appears inside the input when empty and floats above the value as a mini label once the user enters a value... |
| `readOnly` | `boolean` | No | — | Whether the input is read-only (HTML standard casing). |
| `ref` | `Ref<HTMLInputElement>` | No | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (... |
| `required` | `boolean` | No | — | Whether the input is required before form submission. |
| `role` | `string` | No | — | Role attribute for accessibility. |
| `showIcon` | `boolean` | No | `true` | Whether to show the calendar icon |
| `size` | `"large" | "small"` | No | — | Adjusts the interface to either have small or large spacing. |
| `tabIndex` | `number` | No | — | Tab index for keyboard navigation. |
| `value` | `Date` | No | — | A Date object value (e.g., `new Date("11/11/2011")`) |