Add date time component usage guides

.env.pullrequest

@@ -0,0 +1,4 @@
+# Point to ix repo PR #2359 with the datetime-input component
+DOCS_BRANCH='docs/date-time-components-guides'
+DOCS_BRANCH_TYPE='pull request'
+DOCS_PR_NUMBER='2359'

docs/components/date-picker/guide.mdx

@@ -0,0 +1,68 @@
+---
+doc-type: 'tab-item'
+---
+
+# Date picker - Usage
+
+![Date picker anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7436-1700&t=BStIEA03mmCLaHAL-4)
+
+1. Month and year navigation
+2. Weekday labels
+3. Week numbers
+4. Selected date or date range
+5. Confirm [button](../button)
+
+## Options
+
+- **Value**: Defines the selected date or date range.
+- **Single selection**: By default, users select date ranges. Use single selection to allow selecting a single date.
+- **Format**: Define the date format that determines how dates are displayed, e.g. `yyyy/LL/dd` for `2024/06/15`.
+- **Week start**: Define which day the week starts on. By default, it will be defined based on the locale.
+- **Week numbers**: Show calendar weeks on the left side of the calendar when needed for reference.
+- **Min and max dates**: Restrict the selectable date range by defining the earliest and latest dates users can choose.
+- **Corners**: By default, date pickers show rounded corners to be consistent with the [dropdown](../dropdown). Use straight, left or right corners to combine with other components.
+
+## Behavior in context
+
+- **Range selection**: In range mode users select a start date and then an end date. The time period between both dates is visually highlighted to provide clear feedback.
+- **Month navigation**: Users can navigate between months using the arrow buttons in the header or the dropdown menu to quickly jump to a specific month and year.
+- **Interaction**: Users can navigate through the date picker using the keyboard. The following keys are supported:
+  - **Tab**: Navigate between areas of the date picker (header, body, footer).
+  - **Arrow keys**: Move through dates in the calendar.
+  - **Enter or click**: Select the highlighted date.
+  - **Escape**: Close date pickers when used in a dropdown. If header dropdown for month/year selection is open, it closes first.
+
+## States
+
+Individual calendar dates within a date picker have five states: Default, hover, active, disabled and focused. Dates outside the allowed range appear in a disabled state and cannot be selected.
+
+![Date picker states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7436-1708&t=BStIEA03mmCLaHAL-4)
+
+## Dos and Don’ts
+
+<div class="dos-and-donts" markdown>
+<div class="dos" markdown>
+
+- Do use date pickers to ensure accurate date selection
+- Do provide clear labels when the date picker is used in a form context
+- Do ensure the date picker is accessible via keyboard navigation
+- Do use range selection for date periods like booking dates or report timeframes
+- Do set min and max dates to prevent invalid date selections
+
+</div>
+<div class="donts" markdown>
+
+- Don’t use date pickers for dates that are far in the past or future, use [date inputs](../input) instead
+- Don’t clutter the date picker interface with unnecessary options
+- Don’t forget to handle empty or invalid date states in your validation logic
+
+</div>
+</div>
+
+## Related
+
+- [Date input](../input-date)
+- [Date time picker](../date-time-picker)
+- [Time picker](../time-picker)
+- [Writing guidelines for date and time](../../guidelines/language/formatting/date.mdx)
+- [W3C date picker accessibility reference](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/)

docs/components/date-time-picker/guide.mdx

@@ -0,0 +1,69 @@
+---
+doc-type: 'tab-item'
+---
+
+# Date time picker - Usage
+
+![Date time picker anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7440-82856&t=BStIEA03mmCLaHAL-4)
+
+1. [Date picker](../date-picker)
+2. [Time picker](../time-picker)
+3. Confirm [button](../button)
+
+## Options
+
+- **Value**: See [date picker](../date-picker/guide#options) and [time picker](../time-picker/guide#options).
+- **Single selection**: See [date picker](../date-picker/guide#options).
+- **Format**: Choose the date and time format, e.g. `yyyy/LL/dd` and `HH:mm:ss`.
+- **Min and max dates**: See [date picker](../date-picker/guide#options).
+- **Date picker appearance**: See [date picker](../date-picker/guide#options).
+  - **Week start**: Define which day the week starts on. By default, it will be defined based on the locale.
+  - **Week numbers**: Show calendar weeks on the left side of the calendar when needed for reference.
+- **Time picker appearance**: See [time picker](../time-picker/guide#options).
+  - **Time reference**: Show time reference input for AM/PM notation when using 12-hour time format.
+  - **Header**: Customize the header of the time picker.
+- **Corners**: By default, date time pickers show rounded corners to be consistent with the [dropdown](../dropdown). Use straight, left or right corners to combine with other components.
+
+## Behavior in context
+
+- **Combined selection**: Users select both a date and a time before confirming their choice. The selection is only finalized when the confirmation button is clicked.
+- **Range selection**: Range mode allows users to select a start and end date while using one shared time value for both. If start and end need different times, use two separate date time pickers instead.
+- **Month navigation**: Users can navigate between months using the previous and next buttons in the header. This allows quick access to dates outside the current view.
+- **Interaction**: Users can navigate through the date time picker using the keyboard. The following keys are supported:
+  - **Tab**: Navigate between areas of the picker (header, body, time input, footer).
+  - **Arrow keys**: Move through dates in the date picker and times in the time picker.
+  - **Enter or click**: Select the highlighted date or time.
+  - **Escape**: Close the date time picker when used in a dropdown. If the header dropdown for month/year selection is open, it closes first.
+
+## States
+
+Individual calendar dates within a date time picker have five states: Default, hover, active, disabled and focused. Dates outside the allowed range appear in a disabled state and cannot be selected (see [date picker](../date-picker/guide#states) and [time picker](../time-picker/guide#states) for reference).
+
+## Dos and Don’ts
+
+<div class="dos-and-donts" markdown>
+<div class="dos" markdown>
+
+- Do use date time pickers when both date and time information are required
+- Do ensure the date time picker is accessible via keyboard navigation
+- Do use range selection for time periods like booking appointments or scheduling events
+- Do set appropriate min and max dates to prevent invalid selections
+
+</div>
+<div class="donts" markdown>
+
+- Don’t use date time pickers when only a date or only a time is needed (use [date pickers](../date-picker) or [time pickers](../time-picker) instead)
+- Don’t forget to validate both date and time inputs in your form logic
+- Don’t use date time pickers for dates that are far in the past or future without setting appropriate min and max constraints
+- Don’t clutter the interface with unnecessary time precision when approximate times are sufficient
+
+</div>
+</div>
+
+## Related
+
+- [Date picker](../date-picker)
+- [Time picker](../time-picker)
+- [Date time input](../input-date-time)
+- [Writing guidelines for date and time](../../guidelines/language/formatting/date.mdx)
+- [W3C date picker accessibility reference](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/)

docs/components/input-date-time/code.mdx

@@ -0,0 +1,44 @@
+---
+doc-type: 'tab-item'
+formReady: true
+---
+import DatetimeInputPlayground from '@site/docs/autogenerated/playground/datetime-input.mdx';
+import DatetimeInputDisabledPlayground from '@site/docs/autogenerated/playground/datetime-input-disabled.mdx';
+import DatetimeInputLabelPlayground from '@site/docs/autogenerated/playground/datetime-input-label.mdx';
+import DatetimeInputReadonlyPlayground from '@site/docs/autogenerated/playground/datetime-input-readonly.mdx';
+import DatetimeInputValidationPlayground from '@site/docs/autogenerated/playground/datetime-input-validation.mdx';
+import DatetimeInputWithSlotsPlayground from '@site/docs/autogenerated/playground/datetime-input-with-slots.mdx';
+import DatetimeInputMinMaxDatePlayground from '@site/docs/autogenerated/playground/datetime-input-min-max-date.mdx';
+import PropsApi from '@site/docs/autogenerated/api/ix-datetime-input/api.mdx';
+
+# Date time input - Code
+
+## Basic
+
+<DatetimeInputPlayground height="28rem" />
+
+## Disabled
+
+<DatetimeInputDisabledPlayground />
+
+## Label
+
+<DatetimeInputLabelPlayground height="28rem" />
+
+## Readonly
+
+<DatetimeInputReadonlyPlayground />
+
+## Validation
+
+<DatetimeInputValidationPlayground height="40rem" />
+
+## Slots
+
+<DatetimeInputWithSlotsPlayground height="28rem" />
+
+## Min- and max-date
+
+<DatetimeInputMinMaxDatePlayground height="28rem" />
+
+<PropsApi />

docs/components/input-date-time/guide.mdx

@@ -0,0 +1,87 @@
+---
+doc-type: 'tab-item'
+formReady: true
+---
+
+# Date time input - Usage
+
+![Date time input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7441-86110&t=BStIEA03mmCLaHAL-4)
+
+1. Label
+2. Required field indicator
+3. Current date and time value
+4. Calendar [icon button](../icon-button)
+5. [Input field](../input)
+6. [Date time picker](../date-time-picker)
+7. Month and year navigation
+8. Weekday labels
+9. Selected date or date range
+10. Time picker
+11. Confirm [button](../button)
+
+## Options
+
+- **Label**: See [form field](../forms-field/guide#options).
+- **Required**: See [form field](../forms-field/guide#options).
+- **Helper text**: See [form field](../forms-field/guide#options).
+- **Feedback text**: See [form field](../forms-field/guide#options).
+- **Show text as tooltip**: See [form field](../forms-field/guide#options).
+- **Placeholder**: See [form field](../forms-field/guide#options). We typically use a placeholder to show an example date time format to assist users when the field is empty.
+- **Text alignment**: See [form field](../forms-field/guide#options) (by default at start).
+- **Error message**: Feedback text when date or time is not parsable. We typically use this to inform users that the entered date time format is incorrect and guide them to enter a valid date and time.
+- **Format**: Choose the date and time format, e.g. `yyyy/LL/dd` and `HH:mm:ss`.
+- **Min and max dates**: Restrict the selectable date range by defining the earliest and latest dates users can choose.
+- **Date time picker appearance**: See [date time picker](../date-time-picker/guide#options).
+  - **Week start**: Define which day the week starts on. By default, it will be defined based on the locale.
+  - **Week numbers**: Show calendar weeks on the left side of the calendar when needed for reference.
+
+## Behavior in context
+
+- **Interaction**:
+  - Click opens date time pickers. Via keyboard focus followed by arrow down key also opens it.
+  - Use mouse or keyboard arrows to navigate to the desired date and adjust the time.
+  - Confirm closes the date time picker and applies the selection.
+  - Typing a valid date and time into input field closes the picker.
+  - Escape key closes the date time picker.
+- **Validation**:
+  - Use feedback text for validation types valid, info, warning and invalid.
+  - Invalid feedback is automatically provided if the entered date or time is not parsable.
+  - Refer to the [validation](../forms-validation) chapter for detailed guidelines.
+- **Overflow**: The input field should be wide enough to display the full date and time without truncation.
+- **Alignment**: Date time inputs are aligned to the left by default.
+- **Combined selection**: Users select both a date and a time before confirming their choice. The selection is only finalized when the confirmation button is clicked.
+
+## States
+
+Date time input has five states: Default, hover, disabled, read-only and focused.
+
+![Date time input states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7441-86123&t=BStIEA03mmCLaHAL-4)
+
+## Dos and Don'ts
+
+<div class="dos-and-donts" markdown>
+<div class="dos" markdown>
+
+- Do use consistent date and time formats throughout the application to avoid confusion
+- Do provide clear instructions on the expected format, such as "Enter the date time in yyyy/mm/dd HH:mm format"
+- Do consider localization to adapt date and time formats to local conventions
+- Do use separate inputs for start and end date times when defining time ranges
+
+</div>
+<div class="donts" markdown>
+
+- Don't use date time inputs when only a date or only a time is needed (use [date input](../input-date) or [time input](../input-time) instead)
+
+</div>
+</div>
+
+## Related
+
+- [Time picker](../time-picker)
+- [Date time picker](../date-time-picker)
+- [Time input](../input-time)
+- [Date input](../input-date)
+- [Forms field](../forms-field)
+- [Validation](../forms-validation)
+- [Writing guidelines for date and time](../../guidelines/language/formatting/date.mdx)
+- [W3C date picker accessibility reference](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/)

docs/components/input-date-time/index.mdx

@@ -0,0 +1,6 @@
+---
+doc-type: "tabs"
+description: 'Date time input provides a versatile interface for selecting both date and time values, offering a seamless way to input date and time information either as a standalone element or within a dropdown.'
+title: 'Date time input'
+deprecated:
+---

docs/components/input-date/guide.md

@@ -5,8 +5,6 @@ formReady: true
 
 # Date input - Usage
 
-The date input component is typically used in forms, filters and scheduling tools to ensure consistent and accurate date entries. By standardizing date input, it helps maintain data integrity and improves the user experience in applications requiring precise date information.
-
 ![Date input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3629-6200&t=ADQCetGKOEH1WG2r-4)
 
 1. Label
@@ -18,20 +16,20 @@ The date input component is typically used in forms, filters and scheduling tool
 7. Month and year selection
 8. Weekdays
 9. Week numbers
-10. Indicator for current day
-11. Indicator for selected day
+10. Current day
+11. Selected date or date range
 
 ## Options
 
-- **Label**: See [form field](../forms-field).
-- **Required**: See [form field](../forms-field).
-- **Helper text**: See [form field](../forms-field).
-- **Feedback text**: See [form field](../forms-field).
-- **Show text as tooltip**: See [form field](../forms-field).
-- **Placeholder**: See [form field](../forms-field). We typically use a placeholder to show an example date format to assist users when the field is empty.
-- **Text alignment:** See [form field](../forms-field) (by default at start).
+- **Label**: See [form field](../forms-field/guide#options).
+- **Required**: See [form field](../forms-field/guide#options).
+- **Helper text**: See [form field](../forms-field/guide#options).
+- **Feedback text**: See [form field](../forms-field/guide#options).
+- **Show text as tooltip**: See [form field](../forms-field/guide#options).
+- **Placeholder**: See [form field](../forms-field/guide#options). We typically use a placeholder to show an example date format to assist users when the field is empty.
+- **Text alignment:** See [form field](../forms-field/guide#options) (by default at start).
 - **Error message**: Feedback text when date is not parsable. We typically use this to inform users that the entered date format is incorrect and guide them to enter a valid date.
-- **Format**: Specify the date format, default ‘yyyy/LL/dd’ to ensure that dates are entered in a consistent and recognizable format.
+- **Format**: Specify the date format, default `yyyy/LL/dd` to ensure that dates are entered in a consistent and recognizable format.
 
 ## Behavior in context
 
@@ -72,4 +70,5 @@ Date input has five states: Default, hover, disabled, read-only and focused.
 - [Validation](../forms-validation)
 - [Dropdown](../dropdown)
 - [Input](../input)
-- [Select](../select)
+- [Select](../select)
+- [W3C date picker accessibility reference](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/)

docs/components/input-time/guide.mdx

@@ -24,16 +24,15 @@ Time inputs are typically used in forms, filters and scheduling tools to ensure
 - **Feedback text**: See [form field](../forms-field).
 - **Show text as tooltip**: See [form field](../forms-field).
 - **Placeholder**: See [form field](../forms-field). We typically use a placeholder to show an example time format to assist users when the field is empty.
-- **Text alignment:** See [form field](../forms-field) (by default at start).
+- **Text alignment:** See [form field](../forms-field/guide#options) (by default at start).
 - **Error message**: Feedback text when time is not parsable. We typically use this to inform users that the entered time format is incorrect and guide them to enter a valid time.
-- **Format**: Specify the time format to ensure that times are entered in a consistent and recognizable format. Default is ‘TT’ which is the localized 24-hour time with seconds (read more in the [UX writing guides](./../../guidelines/language/writing-style-guide-getting-started)).
-  - **Columns**: Show the respective columns in the time picker (see [time picker](../time-picker)).
-  - **Intervals**: Define intervals to restrict allowed values (see [time picker](../time-picker)).
-- **Time picker**:
-  - **Header**: Hide the header when there is a label on the input or if the context is conveyed in another way (see [time picker](../time-picker)).
-  - **Corners**: See [time picker](../time-picker).
-  - **Standalone appearance**: See [time picker](../time-picker).
-
+- **Format**: Specify the time format to ensure that times are entered in a consistent and recognizable format. Default is `TT` which is the localized 24-hour time with seconds (read more in the [UX writing guidelines](./../../guidelines/language/writing-style-guide-getting-started)).
+  - **Columns**: Show the respective columns in the time picker (see [time picker](../time-picker/guide#options)).
+  - **Intervals**: Define intervals to restrict allowed values (see [time picker](../time-picker/guide#options)).
+- **Time picker**: See [time picker](../time-picker/guide#options)
+  - **Header**: Hide the header when there is a label on the input, or if the context is conveyed in another way.
+  - **Corners**
+  - **Standalone appearance**
 ## Behavior in context
 
 - **Interaction**:
@@ -76,8 +75,8 @@ Time input has five states: Default, hover, disabled, read-only and focused.
 
 - [Time picker](../time-picker)
 - [Date time picker](../date-time-picker)
+- [Date time input](../input-date-time)
 - [Forms field](../forms-field)
 - [Validation](../forms-validation)
-- [Dropdown](../dropdown)
-- [Input](../input)
-- [Select](../select)
+- [Writing guidelines for date and time](../../guidelines/language/formatting/date.mdx)
+- [W3C date picker accessibility reference](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/)

docs/components/time-picker/guide.mdx

@@ -61,3 +61,4 @@ An individual time item of a time picker has five states: Default, hover, active
 - [Date picker](../date-picker)
 - [Date time picker](../date-time-picker)
 - [Dropdown](../dropdown)
+- [W3C date picker accessibility reference](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/)