Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improve component validation documentation #3640

Open
wants to merge 13 commits into
base: latest
Choose a base branch
from
+159 −42
Open

docs: improve component validation documentation #3640

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
83dd517
docs: explain constraint validation
vursen Oct 1, 2024
6915e9b
wip
vursen Oct 1, 2024
0a7d749
wip
vursen Oct 1, 2024
9f2a1d5
update validation section for DateTimePicker
vursen Oct 2, 2024
8463056
add missing .collapsible-list class
vursen Oct 2, 2024
dcf9da1
improve validation section for NumberField
vursen Oct 2, 2024
6e798d0
add missing anchor annotation
vursen Oct 2, 2024
d71d5db
use better wording
vursen Oct 2, 2024
89e4045
Merge branch 'latest' into explain-text-field-validation
vursen Oct 3, 2024
8940119
fix some issues
vursen Oct 3, 2024
4e4aa16
Update articles/components/date-time-picker/index.adoc
vursen Oct 3, 2024
77189a5
Merge branch 'latest' into explain-text-field-validation
vursen Oct 3, 2024
94d3117
include Allowed Characters in NumberField constraints
vursen Oct 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions articles/components/_input-field-common-features.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,21 +144,24 @@


////
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.

Check failure on line 155 in articles/components/_input-field-common-features.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'unparsable'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'unparsable'?", "location": {"path": "articles/components/_input-field-common-features.adoc", "range": {"start": {"line": 155, "column": 93}}}, "severity": "ERROR"}
====
// 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.
====
Expand Down Expand Up @@ -192,11 +195,15 @@
.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.
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[]


// 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[]


////
Expand Down
11 changes: 9 additions & 2 deletions articles/components/combo-box/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,9 +360,14 @@ endif::[]
--


// Constraints
[.collapsible-list]
== Validation

include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;allowed-chars]
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:

include::{articles}/components/_input-field-common-features.adoc[tags=required;allowed-chars]

[.example]
--
Expand All @@ -388,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

Expand Down
23 changes: 17 additions & 6 deletions articles/components/date-picker/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,18 +48,26 @@ 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 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:

=== 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]
--

ifdef::lit[]
[source,html]
----
Expand All @@ -82,10 +90,11 @@ include::{root}/frontend/demo/component/datepicker/react/date-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

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 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]
--
Expand All @@ -111,7 +120,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.


== Week Numbers

Expand Down
25 changes: 20 additions & 5 deletions articles/components/date-time-picker/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,11 +150,23 @@ endif::[]
--


[.collapsible-list]
== 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-and-max-value]
.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]
--
Expand All @@ -180,10 +192,11 @@ 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

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 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]
--
Expand All @@ -208,7 +221,9 @@ include::{root}/frontend/demo/component/datetimepicker/react/date-time-picker-cu
----
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

Expand Down
19 changes: 15 additions & 4 deletions articles/components/email-field/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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:

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[]
Expand All @@ -112,6 +119,10 @@ 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

Expand Down
32 changes: 28 additions & 4 deletions articles/components/number-field/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,15 +74,34 @@ 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:

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.
====

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]
--

ifdef::lit[]
[source,typescript]
----
Expand All @@ -105,6 +124,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.
Expand Down
13 changes: 11 additions & 2 deletions articles/components/password-field/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,9 +99,14 @@ 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 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:

include::{articles}/components/_input-field-common-features.adoc[tags=required;min-and-max-length;allowed-chars]

[.example]
--
Expand All @@ -127,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

Expand Down
13 changes: 11 additions & 2 deletions articles/components/text-area/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,9 +130,14 @@ 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 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:

include::{articles}/components/_input-field-common-features.adoc[tags=required;pattern;min-and-max-length;allowed-chars]

[.example]
--
Expand All @@ -158,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

Expand Down
15 changes: 13 additions & 2 deletions articles/components/text-field/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,16 @@ 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 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:

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]
--
Expand All @@ -99,6 +106,10 @@ 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

Expand Down
Loading
Loading