From 42d54884acc089a89f6cbf9e9adbfdcbdb6c49ec Mon Sep 17 00:00:00 2001 From: Felix Leist Date: Thu, 17 Oct 2024 17:52:35 +0200 Subject: [PATCH 1/3] docs: date input ux description --- .../docs/controls/_date-input_code.mdx | 44 ++++++++++++ .../docs/controls/_date-input_styleguide.mdx | 69 +++++++++++++++++++ .../docs/controls/date-input.mdx | 46 ++----------- 3 files changed, 118 insertions(+), 41 deletions(-) create mode 100644 packages/documentation/docs/controls/_date-input_code.mdx create mode 100644 packages/documentation/docs/controls/_date-input_styleguide.mdx diff --git a/packages/documentation/docs/controls/_date-input_code.mdx b/packages/documentation/docs/controls/_date-input_code.mdx new file mode 100644 index 0000000000..2e392d6fa6 --- /dev/null +++ b/packages/documentation/docs/controls/_date-input_code.mdx @@ -0,0 +1,44 @@ +import Playground from '@site/src/components/PlaygroundV2'; +import Props from '@site/docs/auto-generated/ix-date-input/props.md'; +import Events from '@site/docs/auto-generated/ix-date-input/events.md'; +import Tags from '@site/docs/auto-generated/ix-date-input/tags.md'; + +# Date input + + + +## Examples + +### Basic + + + +### Disabled + + + +### Label + + + +### Readonly + + + +### Validation + + + +## API + +### Properties + + + +### Events + + diff --git a/packages/documentation/docs/controls/_date-input_styleguide.mdx b/packages/documentation/docs/controls/_date-input_styleguide.mdx new file mode 100644 index 0000000000..c8c630540e --- /dev/null +++ b/packages/documentation/docs/controls/_date-input_styleguide.mdx @@ -0,0 +1,69 @@ +The Date input component allows users to enter and select a date in a standardized format. + +![Date input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3629-6200&t=ADQCetGKOEH1WG2r-4) +1. Label +2. Required field indicator (optional) +3. Current value +4. Calendar icon button +5. Input field +6. Date dropdown +7. Month and year selection +8. Weekdays +9. Week numbers  +10. Indicator for current day +11. Indicator for selected day + +## Options + +- **Label**: [See form field](./forms/forms-field.md) +- **Value**: [See form field](./forms/forms-field.md) +- **Required**: [See form field](./forms/forms-field.md) +- **Helper text**: [See form field](./forms/forms-field.md) +- **Feedback text**: [See form field](./forms/forms-field.md) +- **Show text as tooltip**: [See form field](./forms/forms-field.md) +- **Placeholder text**: [See form field](./forms/forms-field.md). Use to show example date format to assist users when field is empty +- **Error message**: Feedback text when date is not parsable +- **Format**: Define date format, default 'yyyy/LL/dd', See Luxon JavaScript library + +## Behavior + +- **Interaction**: + - Click or focus opens date picker + - Use mouse or keyboard arrows to navigate to desired date + - Selecting a date in date picker with mouse click or enter closes date picker + - Typing a date into input field with valid format closes date picker + - Escape key closes date picker +- **Validation**: + - Use feedback text for validation types valid, info, warning and invalid + - Invalid feedback automatically provided if entered date in not parsable + - Refer to the validation chapter for detailed guidelines +- **Overflow**: The input field should be wide enough to display the full date without truncation +- **Alignment**: Inputs are always aligned to the left + +## States + +Date input has five states: Default, hover, disabled, read-only and focused. + +![Date input states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3989-2545&t=ADQCetGKOEH1WG2r-4) + + +## Dos and Don’ts + +- Do use consistent date formats: Ensure the date format is uniform throughout the application to avoid confusion. +- Do use separate inputs for date ranges: Provide distinct input fields for the start and end dates to make it easier for users to enter and understand date ranges. +- Do provide clear instructions: Clearly indicate the required date format to users. For example, “Please enter the date in yyyy-MM-dd format.” +- Do handle time zones: If time zones are relevant, ensure that the date input accounts for them and is clearly labeled. +- Do consider localization: Adapt date formats to the local conventions of your users if your application is used internationally. +- Don't use ambiguous formats: Do not use date formats that can be easily misinterpreted, such as MM/dd/yyyy or dd/MM/yyyy without clear context. +- Don't allow free text without validation: Avoid allowing users to enter dates as free text without any validation or formatting guidance. + +## Related patterns + +- [Date dropdown](./date-dropdown.md) +- [Date picker](./date-picker.md) +- [Date time picker](./date-picker.md) +- [Forms field](./forms/forms-field.md) +- [Validation](./forms/forms-validation.md) +- [Dropdown](./dropdown.md) +- [Input](input.mdx) +- [Select](select.mdx) diff --git a/packages/documentation/docs/controls/date-input.mdx b/packages/documentation/docs/controls/date-input.mdx index 2e392d6fa6..1bbfa130ed 100644 --- a/packages/documentation/docs/controls/date-input.mdx +++ b/packages/documentation/docs/controls/date-input.mdx @@ -1,44 +1,8 @@ -import Playground from '@site/src/components/PlaygroundV2'; -import Props from '@site/docs/auto-generated/ix-date-input/props.md'; -import Events from '@site/docs/auto-generated/ix-date-input/events.md'; -import Tags from '@site/docs/auto-generated/ix-date-input/tags.md'; +import DocsTabs from '@site/src/components/DocsTabs'; -# Date input - - - -## Examples - -### Basic - - - -### Disabled - - - -### Label - - +import DocsUx from './\_date-input_styleguide.mdx' +import DocsCode from './\_date-input_code.mdx' -### Readonly - - - -### Validation - - - -## API - -### Properties - - - -### Events +# Date input - + From 3d95329563220aac578bd1ec417c97985284d879 Mon Sep 17 00:00:00 2001 From: Felix Leist Date: Mon, 21 Oct 2024 17:57:41 +0200 Subject: [PATCH 2/3] docs: adapt date input ux description --- .../docs/controls/_date-input_styleguide.mdx | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/packages/documentation/docs/controls/_date-input_styleguide.mdx b/packages/documentation/docs/controls/_date-input_styleguide.mdx index c8c630540e..bbdd567ab3 100644 --- a/packages/documentation/docs/controls/_date-input_styleguide.mdx +++ b/packages/documentation/docs/controls/_date-input_styleguide.mdx @@ -1,8 +1,8 @@ -The Date input component allows users to enter and select a date in a standardized format. +The date input component enables users to enter and select a date in a standardized format. We typically use this component in forms, calendars, and scheduling tools to ensure consistent and accurate date entries. ![Date input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3629-6200&t=ADQCetGKOEH1WG2r-4) 1. Label -2. Required field indicator (optional) +2. Required field indicator 3. Current value 4. Calendar icon button 5. Input field @@ -15,30 +15,30 @@ The Date input component allows users to enter and select a date in a standardiz ## Options -- **Label**: [See form field](./forms/forms-field.md) -- **Value**: [See form field](./forms/forms-field.md) -- **Required**: [See form field](./forms/forms-field.md) -- **Helper text**: [See form field](./forms/forms-field.md) -- **Feedback text**: [See form field](./forms/forms-field.md) -- **Show text as tooltip**: [See form field](./forms/forms-field.md) -- **Placeholder text**: [See form field](./forms/forms-field.md). Use to show example date format to assist users when field is empty -- **Error message**: Feedback text when date is not parsable -- **Format**: Define date format, default 'yyyy/LL/dd', See Luxon JavaScript library +- **Label**: See [form field](./forms/forms-field.md) +- **Value**: See [form field](./forms/forms-field.md) +- **Required**: See [form field](./forms/forms-field.md) +- **Helper text**: See [form field](./forms/forms-field.md) +- **Feedback text**: See [form field](./forms/forms-field.md) +- **Show text as tooltip**: See [form field](./forms/forms-field.md) +- **Placeholder**: See [form field](./forms/forms-field.md). We typically use a placeholder to show an example date format to assist users when the field is empty. +- **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’. We typically use this to ensure that dates are entered in a consistent and recognizable format, leveraging the Luxon JavaScript library for parsing and formatting. -## Behavior +## Behavior in context - **Interaction**: - - Click or focus opens date picker - - Use mouse or keyboard arrows to navigate to desired date - - Selecting a date in date picker with mouse click or enter closes date picker - - Typing a date into input field with valid format closes date picker - - Escape key closes date picker + - Click or focus opens date picker. + - Use mouse or keyboard arrows to navigate to desired date. + - Selecting a date in date picker with mouse click or enter closes the date picker. + - Typing a date into input field with valid format closes the date picker. + - Escape key closes the date picker. - **Validation**: - - Use feedback text for validation types valid, info, warning and invalid - - Invalid feedback automatically provided if entered date in not parsable - - Refer to the validation chapter for detailed guidelines -- **Overflow**: The input field should be wide enough to display the full date without truncation -- **Alignment**: Inputs are always aligned to the left + - Use feedback text for validation types valid, info, warning and invalid. + - Invalid feedback automatically provided if entered date in not parsable. + - Refer to the [validation](./forms/forms-validation.md) chapter for detailed guidelines. +- **Overflow**: The input field should be wide enough to display the full date without truncation. +- **Alignment**: Date inputs are always aligned to the left. ## States @@ -49,13 +49,13 @@ Date input has five states: Default, hover, disabled, read-only and focused. ## Dos and Don’ts -- Do use consistent date formats: Ensure the date format is uniform throughout the application to avoid confusion. -- Do use separate inputs for date ranges: Provide distinct input fields for the start and end dates to make it easier for users to enter and understand date ranges. -- Do provide clear instructions: Clearly indicate the required date format to users. For example, “Please enter the date in yyyy-MM-dd format.” -- Do handle time zones: If time zones are relevant, ensure that the date input accounts for them and is clearly labeled. -- Do consider localization: Adapt date formats to the local conventions of your users if your application is used internationally. -- Don't use ambiguous formats: Do not use date formats that can be easily misinterpreted, such as MM/dd/yyyy or dd/MM/yyyy without clear context. -- Don't allow free text without validation: Avoid allowing users to enter dates as free text without any validation or formatting guidance. +- Do use consistent date formats: Ensure the date format is uniform throughout the application to avoid confusion +- Do use separate inputs for date ranges: Provide distinct input fields for the start and end dates to make it easier for users to enter and understand date ranges +- Do provide clear instructions: Clearly indicate the required date format to users. For example, “Please enter the date in yyyy-MM-dd format” +- Do handle time zones: If time zones are relevant, ensure that the date input accounts for them and is clearly labeled +- Do consider localization: Adapt date formats to the local conventions of your users if your application is used internationally +- Don't use ambiguous formats: Do not use date formats that can be easily misinterpreted, such as 09/08/2006 without clear context +- Don't allow free text without validation: Avoid allowing users to enter dates as free text without any validation or formatting guidance ## Related patterns From 7d1bdfb50c21e5c091d98afadc27b71fea6c6781 Mon Sep 17 00:00:00 2001 From: Felix Leist Date: Thu, 24 Oct 2024 11:59:00 +0200 Subject: [PATCH 3/3] docs: adapt ux description for date input --- .../docs/controls/_date-input_styleguide.mdx | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/packages/documentation/docs/controls/_date-input_styleguide.mdx b/packages/documentation/docs/controls/_date-input_styleguide.mdx index bbdd567ab3..a759d8f904 100644 --- a/packages/documentation/docs/controls/_date-input_styleguide.mdx +++ b/packages/documentation/docs/controls/_date-input_styleguide.mdx @@ -1,4 +1,4 @@ -The date input component enables users to enter and select a date in a standardized format. We typically use this component in forms, calendars, and scheduling tools to ensure consistent and accurate date entries. +The date input component enables users to enter and select a date in a standardized format. We typically use this component in forms, filters, and scheduling tools to ensure consistent and accurate date entries. ![Date input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3629-6200&t=ADQCetGKOEH1WG2r-4) 1. Label @@ -16,14 +16,13 @@ The date input component enables users to enter and select a date in a standardi ## Options - **Label**: See [form field](./forms/forms-field.md) -- **Value**: See [form field](./forms/forms-field.md) - **Required**: See [form field](./forms/forms-field.md) - **Helper text**: See [form field](./forms/forms-field.md) - **Feedback text**: See [form field](./forms/forms-field.md) - **Show text as tooltip**: See [form field](./forms/forms-field.md) - **Placeholder**: See [form field](./forms/forms-field.md). We typically use a placeholder to show an example date format to assist users when the field is empty. - **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’. We typically use this to ensure that dates are entered in a consistent and recognizable format, leveraging the Luxon JavaScript library for parsing and formatting. +- **Format**: Specify the date format, default ‘yyyy/LL/dd’ to ensure that dates are entered in a consistent and recognizable format. ## Behavior in context @@ -49,13 +48,13 @@ Date input has five states: Default, hover, disabled, read-only and focused. ## Dos and Don’ts -- Do use consistent date formats: Ensure the date format is uniform throughout the application to avoid confusion -- Do use separate inputs for date ranges: Provide distinct input fields for the start and end dates to make it easier for users to enter and understand date ranges -- Do provide clear instructions: Clearly indicate the required date format to users. For example, “Please enter the date in yyyy-MM-dd format” -- Do handle time zones: If time zones are relevant, ensure that the date input accounts for them and is clearly labeled -- Do consider localization: Adapt date formats to the local conventions of your users if your application is used internationally -- Don't use ambiguous formats: Do not use date formats that can be easily misinterpreted, such as 09/08/2006 without clear context -- Don't allow free text without validation: Avoid allowing users to enter dates as free text without any validation or formatting guidance +- Do use consistent date formats throughout the application to avoid confusion +- Do use separate inputs for start and end dates to simplify date ranges +- Do provide clear instructions, such as “Enter the date in yyyy/MM/dd format” +- Do handle time zones and label them clearly if relevant +- Do consider localization to adapt date formats to local conventions +- Don't use ambiguous formats like 09/08/2006 without clear context +- Don't allow free text without validation or formatting guidance ## Related patterns