From 83dd517e6e46390ce7bf485af9e8bd433e79b367 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Tue, 1 Oct 2024 15:11:28 +0400 Subject: [PATCH 01/11] docs: explain constraint validation --- .../_input-field-common-features.adoc | 25 +++++++++++++------ articles/components/combo-box/index.adoc | 5 ++-- articles/components/date-picker/index.adoc | 19 +++++++++++--- articles/components/email-field/index.adoc | 18 ++++++++++--- articles/components/password-field/index.adoc | 10 ++++++-- articles/components/text-area/index.adoc | 10 ++++++-- articles/components/text-field/index.adoc | 16 ++++++++++-- 7 files changed, 80 insertions(+), 23 deletions(-) diff --git a/articles/components/_input-field-common-features.adoc b/articles/components/_input-field-common-features.adoc index 1d04752574..09770e6fb2 100644 --- a/articles/components/_input-field-common-features.adoc +++ b/articles/components/_input-field-common-features.adoc @@ -144,21 +144,24 @@ Disabled fields can be useful in situations where they can become enabled based //// -CONSTRAINT FEATURES +VALIDATION FEATURES //// -// tag::constraints-intro[] -[.collapsible-list] -== Constraints -// end::constraints-intro[] - +// tag::bad-input[] +[#bad-input] +.Bad Input +[%collapsible] +==== +Bad input refers to any input that cannot be parsed into a value of the field type. When an unparsable value is entered, the field resets the value to empty and becomes invalid. This constraint is non-configurable and enabled by default. +==== +// end::bad-input[] // tag::required[] [#required] .Required [%collapsible] ==== -Required fields are marked with an indicator next to the label, and become invalid if left empty after having been focused. An error message explaining that the field is required needs to be provided manually. +Required fields are marked with an indicator next to the label, and become invalid if their value is first entered and then cleared. An instruction text at the top of the form explaining the required indicator is recommended. The indicator itself can be customized with the `--lumo-required-field-indicator` style property. ==== @@ -193,10 +196,16 @@ The pattern is a regular expression used to validate the full value entered into [%collapsible] ==== A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don't match the expression are rejected. + +Note, however, that programmatically set values are not subject to this restriction, even if they contain disallowed characters. To validate these values, a pattern constraint can be used in addition. ==== // end::allowed-chars[] - +// tag::binder[] +.Data Binding and Custom Validation +[NOTE] +Flow and Hilla offer an advanced API called Binder that allows you to bind data and add custom validation rules for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. +// end::binder[] //// diff --git a/articles/components/combo-box/index.adoc b/articles/components/combo-box/index.adoc index e8fb895663..b94b478716 100644 --- a/articles/components/combo-box/index.adoc +++ b/articles/components/combo-box/index.adoc @@ -360,9 +360,10 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;allowed-chars] +include::{articles}/components/_input-field-common-features.adoc[tags=required;allowed-chars] [.example] -- diff --git a/articles/components/date-picker/index.adoc b/articles/components/date-picker/index.adoc index 0c8179ef57..4770760df5 100644 --- a/articles/components/date-picker/index.adoc +++ b/articles/components/date-picker/index.adoc @@ -48,14 +48,23 @@ endif::[] The date can be entered directly using the keyboard in the format of the current locale or through the date picker overlay. The overlay opens when the field is clicked or any input is entered when the field is focused. +[.collapsible-list] == Validation -To validate a date entered or selected, various ways may be used. For instance, you may want to allow only dates in a certain range, or you might not want to allow certain dates. Below are some of your options for date validation. +Date Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the date must meet to be considered valid. Validation generally occurs when the user initiates a date change, for example by selecting a date from the overlay or through text input followed by kbd:[Enter]. If the date is invalid, the field is visually highlighted in red, and an error message appears underneath the input. +Below is a list of supported constraints with more detailed information: -=== Min & Max Value +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input,required] +[#min-and-max-value] +.Min & Max Value +[%collapsible] +==== The valid input range of Date Picker can be restricted by defining `min` and `max` values. Dates before the `min` and after the `max` are disabled in the overlay. Helper text can be used to inform the user about the accepted range. +==== + +The following example demonstrates how to specify these constraints and provide error messages: [.example] -- @@ -82,10 +91,12 @@ include::{root}/frontend/demo/component/datepicker/react/date-picker-validation. endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + ifdef::flow,lit[] === Custom Validation -Date Picker supports custom validation, such as limiting the options to Monday through Friday. In the following example, select a date that's on a Sunday or a Saturday to see a custom validation message. +For more advanced cases where constraint validation isn't sufficient, Flow and Hilla offer an API called Binder that allows you to define custom validation rules. This is useful for example when you want to limit the options to Monday through Friday. In the following example, select a date that's on a Sunday or a Saturday to see a custom validation message. [.example] -- @@ -113,6 +124,8 @@ endif::[] -- endif::[] +Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. + == Week Numbers pass:[ ] diff --git a/articles/components/email-field/index.adoc b/articles/components/email-field/index.adoc index 3b612aef79..baf2c4da87 100644 --- a/articles/components/email-field/index.adoc +++ b/articles/components/email-field/index.adoc @@ -75,19 +75,26 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required] +Email Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation generally occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. + +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=required] [#pattern] .Pattern [%collapsible] ==== -The pattern attribute is an additional validation criterion that you can set if, for example, a specific domain is required. The pattern is specified using a regular expression. +The pattern is a regular expression that specifies an email format. Any value that doesn't match the email format invalidates the field. By default, the https://tools.ietf.org/html/rfc5322#[RFC 5322] standard pattern is used. However, you can modify this pattern to add additional restrictions, for example, to require a specific domain. -The example below uses the pattern `.+@example\.com` and only accepts addresses in the `example.com` domain. +The example below uses a modified version of the RFC 5322 pattern and only accepts addresses in the `example.com` domain. ==== +The following example demonstrates how to specify these constraints and provide error messages: + [.example] -- ifdef::lit[] @@ -112,6 +119,9 @@ include::{root}/frontend/demo/component/emailfield/react/email-field-validation. endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] // Readonly and disabled diff --git a/articles/components/password-field/index.adoc b/articles/components/password-field/index.adoc index fb19d5c037..f4d49f7603 100644 --- a/articles/components/password-field/index.adoc +++ b/articles/components/password-field/index.adoc @@ -99,9 +99,15 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;min-and-max-length;allowed-chars] +Password Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation generally occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. + +Below is a list of supported constraints with more detailed information: + + +include::{articles}/components/_input-field-common-features.adoc[tags=required;min-and-max-length;allowed-chars] [.example] -- diff --git a/articles/components/text-area/index.adoc b/articles/components/text-area/index.adoc index cd6d8d2b42..f9d3ca1d43 100644 --- a/articles/components/text-area/index.adoc +++ b/articles/components/text-area/index.adoc @@ -130,9 +130,15 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;pattern;min-and-max-length;allowed-chars] +Text Area provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation generally occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. + +Below is a list of supported constraints with more detailed information: + + +include::{articles}/components/_input-field-common-features.adoc[tags=required;pattern;min-and-max-length;allowed-chars] [.example] -- diff --git a/articles/components/text-field/index.adoc b/articles/components/text-field/index.adoc index 48152a4abe..89149c8716 100644 --- a/articles/components/text-field/index.adoc +++ b/articles/components/text-field/index.adoc @@ -71,9 +71,18 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;pattern;min-and-max-length;allowed-chars] +Text Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation generally occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. + +Below is a list of supported constraints with more detailed information: + +[.example] + +include::{articles}/components/_input-field-common-features.adoc[tags=required;pattern;min-and-max-length;allowed-chars] + +The following example demonstrates how to specify these constraints and provide error messages: [.example] -- @@ -99,6 +108,9 @@ include::{root}/frontend/demo/component/textfield/react/text-field-validation.ts endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] // Readonly and disabled From 6915e9b66bdf99e55b07a18ba18877684319b441 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Tue, 1 Oct 2024 17:08:59 +0400 Subject: [PATCH 02/11] wip --- articles/components/combo-box/index.adoc | 6 ++++++ articles/components/date-picker/index.adoc | 2 +- articles/components/email-field/index.adoc | 2 +- articles/components/password-field/index.adoc | 7 +++++-- articles/components/text-area/index.adoc | 7 +++++-- articles/components/text-field/index.adoc | 2 +- 6 files changed, 19 insertions(+), 7 deletions(-) diff --git a/articles/components/combo-box/index.adoc b/articles/components/combo-box/index.adoc index b94b478716..be28ae0f8a 100644 --- a/articles/components/combo-box/index.adoc +++ b/articles/components/combo-box/index.adoc @@ -363,6 +363,10 @@ endif::[] [.collapsible-list] == Validation +Combo Box provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by selecting an item from the overlay or entering it from the keyboard and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. + +Below is a list of supported constraints with more detailed information: + include::{articles}/components/_input-field-common-features.adoc[tags=required;allowed-chars] [.example] @@ -389,6 +393,8 @@ include::{root}/frontend/demo/component/combobox/react/combo-box-validation.tsx[ endif::[] -- +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled diff --git a/articles/components/date-picker/index.adoc b/articles/components/date-picker/index.adoc index 4770760df5..d2a77b9dec 100644 --- a/articles/components/date-picker/index.adoc +++ b/articles/components/date-picker/index.adoc @@ -51,7 +51,7 @@ The date can be entered directly using the keyboard in the format of the current [.collapsible-list] == Validation -Date Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the date must meet to be considered valid. Validation generally occurs when the user initiates a date change, for example by selecting a date from the overlay or through text input followed by kbd:[Enter]. If the date is invalid, the field is visually highlighted in red, and an error message appears underneath the input. +Date Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the date must meet to be considered valid. Validation typically occurs when the user initiates a date change, for example by selecting a date from the overlay or through text input followed by kbd:[Enter]. If the date is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Below is a list of supported constraints with more detailed information: diff --git a/articles/components/email-field/index.adoc b/articles/components/email-field/index.adoc index baf2c4da87..f3d0a9a312 100644 --- a/articles/components/email-field/index.adoc +++ b/articles/components/email-field/index.adoc @@ -78,7 +78,7 @@ endif::[] [.collapsible-list] == Validation -Email Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation generally occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. +Email Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Below is a list of supported constraints with more detailed information: diff --git a/articles/components/password-field/index.adoc b/articles/components/password-field/index.adoc index f4d49f7603..8c91b9e9db 100644 --- a/articles/components/password-field/index.adoc +++ b/articles/components/password-field/index.adoc @@ -102,11 +102,10 @@ endif::[] [.collapsible-list] == Validation -Password Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation generally occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. +Password Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. Below is a list of supported constraints with more detailed information: - include::{articles}/components/_input-field-common-features.adoc[tags=required;min-and-max-length;allowed-chars] [.example] @@ -133,6 +132,10 @@ include::{root}/frontend/demo/component/passwordfield/react/password-field-valid endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled diff --git a/articles/components/text-area/index.adoc b/articles/components/text-area/index.adoc index f9d3ca1d43..26548acf1e 100644 --- a/articles/components/text-area/index.adoc +++ b/articles/components/text-area/index.adoc @@ -133,11 +133,10 @@ endif::[] [.collapsible-list] == Validation -Text Area provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation generally occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. +Text Area provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. Below is a list of supported constraints with more detailed information: - include::{articles}/components/_input-field-common-features.adoc[tags=required;pattern;min-and-max-length;allowed-chars] [.example] @@ -164,6 +163,10 @@ include::{root}/frontend/demo/component/textarea/react/text-area-validation.tsx[ endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled diff --git a/articles/components/text-field/index.adoc b/articles/components/text-field/index.adoc index 89149c8716..eeb4392768 100644 --- a/articles/components/text-field/index.adoc +++ b/articles/components/text-field/index.adoc @@ -74,7 +74,7 @@ endif::[] [.collapsible-list] == Validation -Text Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation generally occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. +Text Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. Below is a list of supported constraints with more detailed information: From 0a7d749694a326445132956ef29c446544279240 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Tue, 1 Oct 2024 17:39:35 +0400 Subject: [PATCH 03/11] wip --- articles/components/combo-box/index.adoc | 2 +- articles/components/date-picker/index.adoc | 6 +++--- articles/components/time-picker/index.adoc | 21 +++++++++++++++++---- 3 files changed, 21 insertions(+), 8 deletions(-) diff --git a/articles/components/combo-box/index.adoc b/articles/components/combo-box/index.adoc index be28ae0f8a..7f9f4d6617 100644 --- a/articles/components/combo-box/index.adoc +++ b/articles/components/combo-box/index.adoc @@ -363,7 +363,7 @@ endif::[] [.collapsible-list] == Validation -Combo Box provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by selecting an item from the overlay or entering it from the keyboard and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. +Combo Box provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by selecting an item from the overlay or through text input followed by kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. Below is a list of supported constraints with more detailed information: diff --git a/articles/components/date-picker/index.adoc b/articles/components/date-picker/index.adoc index d2a77b9dec..f5e24d559f 100644 --- a/articles/components/date-picker/index.adoc +++ b/articles/components/date-picker/index.adoc @@ -55,7 +55,7 @@ Date Picker provides a validation mechanism based on constraints. Constraints al Below is a list of supported constraints with more detailed information: -include::{articles}/components/_input-field-common-features.adoc[tags=bad-input,required] +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] [#min-and-max-value] .Min & Max Value @@ -96,7 +96,7 @@ It's important to ensure an appropriate error message is configured for each con ifdef::flow,lit[] === Custom Validation -For more advanced cases where constraint validation isn't sufficient, Flow and Hilla offer an API called Binder that allows you to define custom validation rules. This is useful for example when you want to limit the options to Monday through Friday. In the following example, select a date that's on a Sunday or a Saturday to see a custom validation message. +For more advanced cases where constraint validation isn't sufficient, Flow and Hilla offer an API called Binder that allows you to define custom validation rules. This is useful, for example, when you want to limit the options to Monday through Friday. In the following example, select a date that's on a Sunday or a Saturday to see a custom validation message. [.example] -- @@ -122,9 +122,9 @@ include::{root}/frontend/demo/component/datepicker/react/date-picker-custom-vali ---- endif::[] -- -endif::[] Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. +endif::[] == Week Numbers diff --git a/articles/components/time-picker/index.adoc b/articles/components/time-picker/index.adoc index ad0ec5f27b..3f7854c548 100644 --- a/articles/components/time-picker/index.adoc +++ b/articles/components/time-picker/index.adoc @@ -155,12 +155,23 @@ endif::[] -- - +[.collapsible-list] == Validation -=== Minimum & Maximum Value +Time Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the time must meet to be considered valid. Validation typically occurs when the user initiates a time change, for example by selecting a time from the overlay or through text input followed by kbd:[Enter]. If the time is invalid, the field is visually highlighted in red, and an error message appears underneath the input. + +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] -You can define a minimum and maximum value for Time Picker if you need to restrict the input to a specific range: +[#min-and-max-value] +.Min & Max Value +[%collapsible] +==== +The valid input range of Time Picker can be restricted by defining `min` and `max` values. Times before the `min` and after the `max` aren't displayed in the overlay. Helper text can be used to inform the user about the accepted range. +==== + +The following example demonstrates how to specify these constraints and provide error messages: [.example] -- @@ -189,7 +200,7 @@ endif::[] ifdef::flow,lit[] === Custom Validation -If the minimum and maximum values aren't sufficient for validation, you can also apply custom validation. +For more advanced cases where constraint validation isn't sufficient, Flow and Hilla offer an API called Binder that allows you to define custom validation rules. This is useful, for example, when you want to allow time values only within separate intervals, like morning and afternoon slots. In the following example, select 12:30 to see a custom validation message. [.example] -- @@ -214,6 +225,8 @@ include::{root}/frontend/demo/component/timepicker/react/time-picker-custom-vali ---- endif::[] -- + +Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. endif::[] From 9f2a1d57aa0c564915d82a92a29197323f5fe370 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 2 Oct 2024 13:44:20 +0400 Subject: [PATCH 04/11] update validation section for DateTimePicker --- articles/components/date-picker/index.adoc | 2 +- .../components/date-time-picker/index.adoc | 18 +++++++++++++++--- articles/components/time-picker/index.adoc | 2 +- 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/articles/components/date-picker/index.adoc b/articles/components/date-picker/index.adoc index f5e24d559f..9343d6c9e6 100644 --- a/articles/components/date-picker/index.adoc +++ b/articles/components/date-picker/index.adoc @@ -96,7 +96,7 @@ It's important to ensure an appropriate error message is configured for each con ifdef::flow,lit[] === Custom Validation -For more advanced cases where constraint validation isn't sufficient, Flow and Hilla offer an API called Binder that allows you to define custom validation rules. This is useful, for example, when you want to limit the options to Monday through Friday. In the following example, select a date that's on a Sunday or a Saturday to see a custom validation message. +For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to limit the options to Monday through Friday. In the following example, try selecting a date that's on a Sunday or a Saturday to see a custom validation message. [.example] -- diff --git a/articles/components/date-time-picker/index.adoc b/articles/components/date-time-picker/index.adoc index 8c626ebb47..6d7529b1d4 100644 --- a/articles/components/date-time-picker/index.adoc +++ b/articles/components/date-time-picker/index.adoc @@ -152,9 +152,19 @@ endif::[] == Validation -=== Min & Max Values +Date Time Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the date must meet to be considered valid. Validation typically occurs when the user initiates a date change, for example by selecting a date from the overlay or through text input followed by kbd:[Enter]. If the date is invalid, the field is visually highlighted in red, and an error message appears underneath the input. -You can define a `min` and `max` value for Date Time Picker if you need to restrict the input to a specific range: +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] + +.Min & Max Value +[%collapsible] +==== +The valid input range of Date Time Picker can be restricted by defining `min` and `max` values. Dates and times before the `min` and after the `max` aren't available for selection in the overlay. Helper text can be used to inform the user about the accepted range. +==== + +The following example demonstrates how to specify these constraints and provide error messages: [.example] -- @@ -183,7 +193,7 @@ endif::[] ifdef::flow,lit[] === Custom Validation -If the `min` and `max` values aren't enough, you can also apply custom validation. +For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to restrict date selection to weekdays (Monday-Friday) and time selection to opening hours. In the following example, try selecting a date that's on a weekend or a time that's outside opening hours to see a custom validation message. [.example] -- @@ -208,6 +218,8 @@ include::{root}/frontend/demo/component/datetimepicker/react/date-time-picker-cu ---- endif::[] -- + +Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. endif::[] == Week Numbers diff --git a/articles/components/time-picker/index.adoc b/articles/components/time-picker/index.adoc index 3f7854c548..a6f1f793a6 100644 --- a/articles/components/time-picker/index.adoc +++ b/articles/components/time-picker/index.adoc @@ -200,7 +200,7 @@ endif::[] ifdef::flow,lit[] === Custom Validation -For more advanced cases where constraint validation isn't sufficient, Flow and Hilla offer an API called Binder that allows you to define custom validation rules. This is useful, for example, when you want to allow time values only within separate intervals, like morning and afternoon slots. In the following example, select 12:30 to see a custom validation message. +For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to allow time selection only within separate intervals, like morning and afternoon slots. In the following example, try selecting a time that is between opening hours to see a custom validation message. [.example] -- From 8463056870b062a5a01eb539dde4e887121997a2 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 2 Oct 2024 15:40:41 +0400 Subject: [PATCH 05/11] add missing .collapsible-list class --- articles/components/date-time-picker/index.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/articles/components/date-time-picker/index.adoc b/articles/components/date-time-picker/index.adoc index 6d7529b1d4..d8a1c3066c 100644 --- a/articles/components/date-time-picker/index.adoc +++ b/articles/components/date-time-picker/index.adoc @@ -150,6 +150,7 @@ endif::[] -- +[.collapsible-list] == Validation Date Time Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the date must meet to be considered valid. Validation typically occurs when the user initiates a date change, for example by selecting a date from the overlay or through text input followed by kbd:[Enter]. If the date is invalid, the field is visually highlighted in red, and an error message appears underneath the input. From dcf9da182eb03a20bc4a80cd6fe38f079ffabf84 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 2 Oct 2024 17:24:53 +0400 Subject: [PATCH 06/11] improve validation section for NumberField --- articles/components/date-picker/index.adoc | 2 +- articles/components/number-field/index.adoc | 31 +++++++++++++++++++-- articles/components/text-field/index.adoc | 1 + 3 files changed, 30 insertions(+), 4 deletions(-) diff --git a/articles/components/date-picker/index.adoc b/articles/components/date-picker/index.adoc index 9343d6c9e6..8847b2260e 100644 --- a/articles/components/date-picker/index.adoc +++ b/articles/components/date-picker/index.adoc @@ -92,8 +92,8 @@ endif::[] -- It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. - ifdef::flow,lit[] + === Custom Validation For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to limit the options to Monday through Friday. In the following example, try selecting a date that's on a Sunday or a Saturday to see a custom validation message. diff --git a/articles/components/number-field/index.adoc b/articles/components/number-field/index.adoc index 2038316314..538c0a4683 100644 --- a/articles/components/number-field/index.adoc +++ b/articles/components/number-field/index.adoc @@ -74,11 +74,31 @@ include::{root}/frontend/demo/component/numberfield/react/number-field-step-butt endif::[] -- -== Minimum and Maximum Value +[.collapsible-list] +== Validation -The valid input range of a Number Field is set by defining the minimum and maximum values. +Number Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. -You can set the helper text to give information about the range. +Below is a list of supported constraints with more detailed information: + +[.example] + +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] + +[#min-and-max-value] +.Min & Max Value +[%collapsible] +==== +The valid input range of a Number Field can be restricted by defining `min` and `max` values. Helper text can be used to inform the user about the accepted range. +==== + +.Step +[%collapsible] +==== +Refer to the <<#step,Step>> section for more details and an example. +==== + +The following example demonstrates how to create a quantity field using a combination of these constraints: [.example] -- @@ -105,6 +125,11 @@ include::{root}/frontend/demo/component/numberfield/react/number-field-validatio endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + + == Step The step value of a Number Field defines the numeric intervals that are allowed. diff --git a/articles/components/text-field/index.adoc b/articles/components/text-field/index.adoc index eeb4392768..21895c6807 100644 --- a/articles/components/text-field/index.adoc +++ b/articles/components/text-field/index.adoc @@ -112,6 +112,7 @@ It's important to ensure an appropriate error message is configured for each con include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled include::{articles}/components/_input-field-common-features.adoc[tag=readonly-and-disabled] From 6e798d079b46ba9e0adfa96029265fce96e4f4cd Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 2 Oct 2024 17:26:07 +0400 Subject: [PATCH 07/11] add missing anchor annotation --- articles/components/date-time-picker/index.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/articles/components/date-time-picker/index.adoc b/articles/components/date-time-picker/index.adoc index d8a1c3066c..f40963fd3f 100644 --- a/articles/components/date-time-picker/index.adoc +++ b/articles/components/date-time-picker/index.adoc @@ -159,6 +159,7 @@ Below is a list of supported constraints with more detailed information: include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] +[#min-and-max-value] .Min & Max Value [%collapsible] ==== From d71d5dbbd0ae0c2b0e1fa5c4150e7e5bb3b09810 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 2 Oct 2024 19:31:47 +0400 Subject: [PATCH 08/11] use better wording --- articles/components/combo-box/index.adoc | 2 +- articles/components/password-field/index.adoc | 2 +- articles/components/text-area/index.adoc | 2 +- articles/components/text-field/index.adoc | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/components/combo-box/index.adoc b/articles/components/combo-box/index.adoc index 7f9f4d6617..28efb97b84 100644 --- a/articles/components/combo-box/index.adoc +++ b/articles/components/combo-box/index.adoc @@ -363,7 +363,7 @@ endif::[] [.collapsible-list] == Validation -Combo Box provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by selecting an item from the overlay or through text input followed by kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. +Combo Box provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by selecting an item from the overlay or through text input followed by kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value. Below is a list of supported constraints with more detailed information: diff --git a/articles/components/password-field/index.adoc b/articles/components/password-field/index.adoc index 8c91b9e9db..28837c0163 100644 --- a/articles/components/password-field/index.adoc +++ b/articles/components/password-field/index.adoc @@ -102,7 +102,7 @@ endif::[] [.collapsible-list] == Validation -Password Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. +Password Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value. Below is a list of supported constraints with more detailed information: diff --git a/articles/components/text-area/index.adoc b/articles/components/text-area/index.adoc index 26548acf1e..a3d9133e1c 100644 --- a/articles/components/text-area/index.adoc +++ b/articles/components/text-area/index.adoc @@ -133,7 +133,7 @@ endif::[] [.collapsible-list] == Validation -Text Area provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. +Text Area provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value. Below is a list of supported constraints with more detailed information: diff --git a/articles/components/text-field/index.adoc b/articles/components/text-field/index.adoc index 21895c6807..522c41aee3 100644 --- a/articles/components/text-field/index.adoc +++ b/articles/components/text-field/index.adoc @@ -74,7 +74,7 @@ endif::[] [.collapsible-list] == Validation -Text Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints can prevent users from even typing potentially invalid values by immediately rejecting invalid characters. +Text Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value. Below is a list of supported constraints with more detailed information: From 894011967729076f2c1f5b689d95ee300101c9af Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Thu, 3 Oct 2024 13:41:04 +0400 Subject: [PATCH 09/11] fix some issues --- articles/components/date-picker/index.adoc | 4 +--- articles/components/date-time-picker/index.adoc | 5 +++-- articles/components/email-field/index.adoc | 1 + articles/components/number-field/index.adoc | 1 - articles/components/time-picker/index.adoc | 4 ++-- 5 files changed, 7 insertions(+), 8 deletions(-) diff --git a/articles/components/date-picker/index.adoc b/articles/components/date-picker/index.adoc index 8847b2260e..e59ab29f3d 100644 --- a/articles/components/date-picker/index.adoc +++ b/articles/components/date-picker/index.adoc @@ -68,7 +68,6 @@ The following example demonstrates how to specify these constraints and provide [.example] -- - ifdef::lit[] [source,html] ---- @@ -92,7 +91,6 @@ endif::[] -- It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. -ifdef::flow,lit[] === Custom Validation @@ -124,7 +122,7 @@ endif::[] -- Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. -endif::[] + == Week Numbers diff --git a/articles/components/date-time-picker/index.adoc b/articles/components/date-time-picker/index.adoc index f40963fd3f..009e520852 100644 --- a/articles/components/date-time-picker/index.adoc +++ b/articles/components/date-time-picker/index.adoc @@ -192,7 +192,8 @@ include::{root}/frontend/demo/component/datetimepicker/react/date-time-picker-va endif::[] -- -ifdef::flow,lit[] +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + === Custom Validation For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to restrict date selection to weekdays (Monday-Friday) and time selection to opening hours. In the following example, try selecting a date that's on a weekend or a time that's outside opening hours to see a custom validation message. @@ -222,7 +223,7 @@ endif::[] -- Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. -endif::[] + == Week Numbers diff --git a/articles/components/email-field/index.adoc b/articles/components/email-field/index.adoc index f3d0a9a312..69cec4d9e0 100644 --- a/articles/components/email-field/index.adoc +++ b/articles/components/email-field/index.adoc @@ -123,6 +123,7 @@ It's important to ensure an appropriate error message is configured for each con include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled include::{articles}/components/_input-field-common-features.adoc[tag=readonly-and-disabled] diff --git a/articles/components/number-field/index.adoc b/articles/components/number-field/index.adoc index 538c0a4683..2773b45645 100644 --- a/articles/components/number-field/index.adoc +++ b/articles/components/number-field/index.adoc @@ -102,7 +102,6 @@ The following example demonstrates how to create a quantity field using a combin [.example] -- - ifdef::lit[] [source,typescript] ---- diff --git a/articles/components/time-picker/index.adoc b/articles/components/time-picker/index.adoc index a6f1f793a6..510d09ff30 100644 --- a/articles/components/time-picker/index.adoc +++ b/articles/components/time-picker/index.adoc @@ -197,7 +197,8 @@ include::{root}/frontend/demo/component/timepicker/react/time-picker-validation. endif::[] -- -ifdef::flow,lit[] +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + === Custom Validation For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to allow time selection only within separate intervals, like morning and afternoon slots. In the following example, try selecting a time that is between opening hours to see a custom validation message. @@ -227,7 +228,6 @@ endif::[] -- Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. -endif::[] // Basic Features From 4e4aa1602d9b3aa0d4542da162a93dc53f013dc3 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Thu, 3 Oct 2024 12:45:54 +0300 Subject: [PATCH 10/11] Update articles/components/date-time-picker/index.adoc --- articles/components/date-time-picker/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/components/date-time-picker/index.adoc b/articles/components/date-time-picker/index.adoc index 009e520852..0d574ec0a6 100644 --- a/articles/components/date-time-picker/index.adoc +++ b/articles/components/date-time-picker/index.adoc @@ -196,7 +196,7 @@ It's important to ensure an appropriate error message is configured for each con === Custom Validation -For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to restrict date selection to weekdays (Monday-Friday) and time selection to opening hours. In the following example, try selecting a date that's on a weekend or a time that's outside opening hours to see a custom validation message. +For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to restrict date selection to weekdays (Monday-Friday) and time selection to only certain hours. In the following example, try selecting a date that's on a weekend or a time that's outside opening hours to see a custom validation message. [.example] -- From 94d31178ec8ae5f59c781edee339d61961cf9f65 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Thu, 3 Oct 2024 14:37:47 +0400 Subject: [PATCH 11/11] include Allowed Characters in NumberField constraints --- articles/components/_input-field-common-features.adoc | 4 +--- articles/components/number-field/index.adoc | 4 ++-- articles/components/text-field/index.adoc | 2 -- 3 files changed, 3 insertions(+), 7 deletions(-) diff --git a/articles/components/_input-field-common-features.adoc b/articles/components/_input-field-common-features.adoc index 09770e6fb2..a7bff483be 100644 --- a/articles/components/_input-field-common-features.adoc +++ b/articles/components/_input-field-common-features.adoc @@ -195,9 +195,7 @@ The pattern is a regular expression used to validate the full value entered into .Allowed Characters [%collapsible] ==== -A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don't match the expression are rejected. - -Note, however, that programmatically set values are not subject to this restriction, even if they contain disallowed characters. To validate these values, a pattern constraint can be used in addition. +A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don't match the expression are rejected. Note, however, that programmatically set values are not subject to this restriction, even if they contain disallowed characters. ==== // end::allowed-chars[] diff --git a/articles/components/number-field/index.adoc b/articles/components/number-field/index.adoc index 2773b45645..f6f67bd8e7 100644 --- a/articles/components/number-field/index.adoc +++ b/articles/components/number-field/index.adoc @@ -81,8 +81,6 @@ Number Field provides a validation mechanism based on constraints. Constraints a Below is a list of supported constraints with more detailed information: -[.example] - include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] [#min-and-max-value] @@ -98,6 +96,8 @@ The valid input range of a Number Field can be restricted by defining `min` and Refer to the <<#step,Step>> section for more details and an example. ==== +include::{articles}/components/_input-field-common-features.adoc[tags=allowed-chars] + The following example demonstrates how to create a quantity field using a combination of these constraints: [.example] diff --git a/articles/components/text-field/index.adoc b/articles/components/text-field/index.adoc index 522c41aee3..d51bd7f090 100644 --- a/articles/components/text-field/index.adoc +++ b/articles/components/text-field/index.adoc @@ -78,8 +78,6 @@ Text Field provides a validation mechanism based on constraints. Constraints all Below is a list of supported constraints with more detailed information: -[.example] - include::{articles}/components/_input-field-common-features.adoc[tags=required;pattern;min-and-max-length;allowed-chars] The following example demonstrates how to specify these constraints and provide error messages: