Merge branch 'latest' into russell/add-descriptions-testing-upgrading

articles/_vaadin-version.adoc

@@ -1,5 +1,5 @@
 ---
-:vaadin-version: 24.2.1
-:vaadin-flow-version: 24.2.1
+:vaadin-version: 24.2.4
+:vaadin-flow-version: 24.2.3
 :vaadin-seven-version: 7.7.38
 :vaadin-eight-version: 8.20.0

articles/advanced/custom-error-handler.asciidoc → articles/advanced/custom-error-handler.adoc

@@ -7,9 +7,9 @@ order: 145
 
 = Custom Error Handling
 
-You can customize the error views related to navigation between different routes, as described in the <<{articles}/routing/exceptions#, Router Exception Handling>> documentation page.
+You can customize the error views related to navigation between different routes. The handling of router exceptions is described on the <<{articles}/routing/exceptions#, Router Exception Handling>> documentation page.
 
-For other unhandled runtime exceptions, an [classname]`ErrorHandler` class can be used to let users know that something went wrong. To do so, first create a custom [classname]`ErrorHandler` class, then use that class to override the default error handler.
+For other unhandled runtime exceptions, an [classname]`ErrorHandler` class can be used to let users know that something went wrong. To do so, first create a custom [classname]`ErrorHandler` class. Then use that class to override the default error handler.
 
 For example, the following [classname]`CustomErrorHandler` class logs the error and displays a notification to the user:
 
@@ -41,11 +41,22 @@ VaadinSession.getCurrent().setErrorHandler(new CustomErrorHandler());
 
 To apply the custom error handler to all user sessions, you can use a [classname]`SessionInitListener`, which receives an event each time a new [classname]`VaadinSession` is initialized. See the <<session-and-ui-init-listener#,Session and UI Listeners>> documentation page to learn how to create a [classname]`SessionInitListener`.
 
+[classname]`ErrorEvent` has the method [methodname]`getComponent()` to get the handled [classname]`Component`, and the [methodname]`getElement()` method to get the handled [classname]`Element` when the error is thrown, if available.
+
+For example, the following button-click listener has [classname]`ErrorEvent` [methodname]`getComponent()` return the clicked button:
+
+[source,java]
+----
+Button button = new Button("Click me", event -> {
+    throw new IllegalArgumentException("No clicking");
+});
+----
+
 
 [role="since:com.vaadin:[email protected]"]
-== Showing Error Parameter Views for Non-Navigation Exceptions
+== Error Parameter Views for Non-Navigation Exceptions
 
-In the [classname]`DefaultErrorHandler`, it's possible to enable transitioning to an [interfacename]`HasErrorParameter<T extends Exception>` error view on exceptions. This is done by setting the `enableErrorHandlerRedirect` parameter to `true`. See <<{articles}/routing/exceptions#, Error Resolving>> for more information on the [interfacename]`HasErrorParameter`.
+In the [classname]`DefaultErrorHandler`, it's possible to enable transitioning to an [interfacename]`HasErrorParameter<T extends Exception>` error view on exceptions. See the <<{articles}/routing/exceptions#, Error Resolving>> page for more information on the [interfacename]`HasErrorParameter`.
 
 For a customized error handler, the same can be done by using the [classname]`ErrorHandlerUtil` method, [methodname]`handleErrorByRedirectingToErrorView` like so:
 

articles/advanced/i18n-localization.asciidoc

@@ -12,7 +12,7 @@ To use localization and translation strings, the application needs only to have
 
 When using localization in an application, calling for a translation, or when the I18NProvider is used for the first time, the folder resource, `vaadin-i18n` is checked if it contains any `translations.properties` or `translations_[langcode].properties` files. Any language codes are collected from the available property files and added as provided locales in the [classname]`DefaultI18NProvider`.
 
-The file `translations.properties` is a default translation file that'll be used for any [classname]`Locale` that doesn't have a specific translations file. Locale translation files are named as [filename]`translations_fi_FI.properties` or [filename]`translations_de.properties`. The automatic [classname]`Locale` creation supports from one to three parts (e.g., `translations_language_country_variant.properties`).
+The file `translations.properties` is a default translation file that'll be used for any [classname]`Locale` that doesn't have a specific translations file. Locale translation files are named, for example, like [filename]`translations_fi_FI.properties` or [filename]`translations_de.properties`. The automatic [classname]`Locale` creation supports from one to three parts (e.g., `translations_language_country_variant.properties`).
 
 
 == Locale Selection for New Session
@@ -26,7 +26,7 @@ If an exact match (i.e., language and country) is found, it'll be used. Otherwis
 
 Implementing internationalization in an application is a combination of using `I18NProvider` and updating the translations on locale change.
 
-To make this simple, the application classes that control the captions and texts that are localized can implement [interfacename]`LocaleChangeObserver` to receive events related to locale change. This observer is also notified on navigation when the component is attached, but before [methodname]`onAttach()` is called. Any URL parameters from the navigation are set so that they can be used to determine the state.
+To make this simple, the application classes that control the captions and texts that are localized, can implement [interfacename]`LocaleChangeObserver` to receive events related to locale change. This observer is also notified on navigation when the component is attached, but before [methodname]`onAttach()` is called. Any URL parameters from the navigation are set so that they can be used to determine the state.
 
 [source,java]
 ----
@@ -58,6 +58,9 @@ public class MyLocale extends Div {
 
 To use a custom I18N provider with more features than available by the default one, the application needs only to implement [interfacename]`I18NProvider` and define the fully qualified class name in the property, `i18n.provider`.
 
+[NOTE]
+For a Spring project, the property is not needed if the custom provider is a Bean of type [interfacename]`I18NProvider`.
+
 The `i18n.provider` property can be set from the command-line as a system property, as a Servlet initial parameter in the [filename]`web.xml` file, or using the `@WebServlet` annotation.
 
 As a system property, the parameter needs the `vaadin` prefix like this:
@@ -113,13 +116,13 @@ You can provide an [interfacename]`I18NProvider` as a bean if you're using Sprin
 
 
 [[provider-sample-for-translation]]
-== Example of Using I18NProvider for Translation
+== Using I18NProvider for Translation
 
 For this example, the use of Finnish and English is enabled, with Finnish being the default that's used if the user client doesn't specify English as an accepted language. The language [filename]`.properties` files start with "translate": for example, [filename]`translate.properties` for the default, as well as [filename]`translate_fi_FI.properties`, and [filename]`translate_en_GB.properties`.
 
-In this example, the translation properties files are loaded using the class loader. Hence, they should be located on the classpath, for example in the resources folder. For a default Maven setup, this would be `src/main/resources`.
+Here the translation properties files are loaded using the class loader. Hence, they should be located on the classpath, for example in the resources folder. For a default Maven setup, this would be `src/main/resources`.
 
-.Sample I18NProvider Implementation
+.I18NProvider Implementation Example
 [source,java]
 ----
 public class TranslationProvider implements I18NProvider {
@@ -168,7 +171,7 @@ public class TranslationProvider implements I18NProvider {
 
 Vaadin components have support for right-to-left languages. The components work out-of-the-box in this mode. However, to allow your application to support both left-to-right and right-to-left modes, you'll need to make a few changes.
 
-Continuing from the previous examples, suppose that your application now has also been translated into a right-to-left Language, such as Arabic. As well as <<provider-sample-for-translation,following the I18NProvider example>>, in your main layout you can add code such as the following:
+Continuing from the previous examples, suppose your application now has also been translated into a right-to-left Language, such as Arabic. As well as <<provider-sample-for-translation,following the I18NProvider example>>, in your main layout you can add code such as the following:
 
 [source,java]
 ----
@@ -243,9 +246,9 @@ You may want to define the style for right-to-left, as follows:
 }
 ----
 
-Third, you should also pay attention to settings such as `padding`, `margin`, `text-align`, `float` and `transform` in your styles. If your custom element doesn't need to support old browsers, you can replace some properties with *CSS Logical Properties*. The https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties[MDN web documentation] has a full list of CSS Logical Properties and the available values, along with browser support for each property. Flex and Grid containers are usually handled well by the browser and don't require any extra work. You can find more information in this https://rtlstyling.com/posts/rtl-styling/[comprehensive right-to-left styling guide].
+Third, you should also review settings such as `padding`, `margin`, `text-align`, `float` and `transform` in your styles. If your custom element doesn't need to support old browsers, you can replace some properties with *CSS Logical Properties*. The https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties[MDN web documentation] has a full list of CSS Logical Properties and their available values, along with browser support for each property. Flex and Grid containers are usually handled well by the browser and don't require anything extra. You can find more information in this https://rtlstyling.com/posts/rtl-styling/[comprehensive right-to-left styling guide].
 
-For help with adjusting styles for right-to-left mode, you can use the tools available on the https://rtlcss.com/playground/#[RTLCSS] page. There, you can paste in your original styles and it'll generate code that you can use for your element.
+For help with adjusting styles for right-to-left mode, you can use the tools available on the https://rtlcss.com/playground/#[RTLCSS] page. There, you can paste original styles and it'll generate code that you can use for your element.
 
 If your element uses icons or Unicode symbols to define direction (e.g., for a _Back_ button), you may need to use the right icons or symbols for right-to-left mode.
 
@@ -270,7 +273,7 @@ switch (event.key) {
 
 Custom elements that rely on JavaScript calculations for sizing, position, or horizontal scroll, may need some adjustments for right-to-left.
 
-If you have visual tests, you may want to add or update the current ones to also run in right-to-left mode.
+If you have visual tests, you may want to add or update the current ones to run also in right-to-left mode.
 
 [discussion-id]`722E7AE4-191E-4DE8-90F1-CAE8AE6CD3DF`
 

articles/advanced/modifying-the-bootstrap-page.asciidoc → articles/advanced/modifying-the-bootstrap-page.adoc

@@ -127,12 +127,14 @@ This is the best place to customize the application shell, for example to put an
 In Java code, when adding dynamic content during the bootstrap process, use the [interfacename]`AppShellConfigurator` marker interface rather than editing the [filename]`index.html`.
 
 [NOTE]
-There must be a single application shell for the entire Vaadin application, so that no more than one class can implement [interfacename]`AppShellConfigurator`.
+====
+There must be a single application shell for the entire Vaadin application. This way no more than one class can implement [interfacename]`AppShellConfigurator`. Incidentally, [interfacename]`AppShellConfigurator` replaced the obsolete [interfacename]`PageConfigurator` interface.
+
+Application shell class should not extend Vaadin Component, since application shells are intended only for page configuration and are instantiated before the UI is created. Currently, this check is silently ignored, but future Vaadin versions may fail with an exception in this case.
+====
 
-[NOTE]
-[interfacename]`AppShellConfigurator` replaces the obsolete [interfacename]`PageConfigurator` interface.
 
-==== The AppShellConfigurator.configurePage() Method
+==== `AppShellConfigurator.configurePage()` Method
 
 Override [methodname]`configurePage()` to add content to the [filename]`index.html` template by calling the following [classname]`AppShellSettings` methods:
 

articles/components/_styling-section-theming-props.adoc

@@ -0,0 +1,169 @@
+// tag::style-properties[]
+[role="since:com.vaadin:[email protected]"]
+== Style Properties
+The following style properties can be used in CSS stylesheets to customize the appearance of this component.
+
+To apply values to these properties globally in your application UI, place them in a CSS block using the `html {...}` selector.
+ifdef::flow,lit[]
+See <<../../styling/lumo/lumo-style-properties#,Lumo Style Properties>> for more information on style properties.
+endif::[]
+// end::style-properties[]
+
+// tag::input-fields[]
+.Input Field Components Shared Styles
+[NOTE]
+Style properties whose names start with `--vaadin-input-field` are shared among all input field components. To apply them only to a specific type of component, use an element selector like `vaadin-text-field {...}`
+
+// end::input-fields[]
+
+
+// tag::input-surface[]
+=== Field Surface
+
+[cols="1,2,2"]
+|===
+| Feature | Property | Default Value
+
+|Background
+|`--vaadin-input-field-background`
+|`--lumo-contrast-10pct`
+
+|Background, invalid
+|`--vaadin-input-field-invalid-background`
+|`--lumo-error-color-10pct`
+
+|Background, hover highlight color
+|`--vaadin-input-field-hover-highlight`
+|`--lumo-contrast-50pct`
+
+|Background, invalid hover highlight color
+|`--vaadin-input-field-invalid-hover-highlight`
+|`--lumo-error-color-50pct`
+
+|Hover highlight opacity
+|`--vaadin-input-field-hover-highlight-opacity`
+|`0.1`
+
+|Height
+|`--vaadin-input-field-height`
+|`--lumo-size-m`
+
+|Value text color
+|`--vaadin-input-field-value-color`
+|`--lumo-body-text-color`
+
+|Value font size
+|`--vaadin-input-field-value-font-size`
+|`--lumo-font-size-m`
+
+|Value font weight
+|`--vaadin-input-field-value-font-weight`
+|`400`
+
+|Placeholder text color
+|`--vaadin-input-field-placeholder-color`
+|`--lumo-secondary-text-color`
+
+|Border radius
+|`--vaadin-input-field-border-radius`
+|`--lumo-border-radius-m`
+
+|Read-only border
+|`--vaadin-input-field-readonly-border`
+|`1px dashed --lumo-contrast-30pct`
+
+|===
+// end::input-surface[]
+
+
+// tag::label-helper-error[]
+=== Label
+
+[cols="1,2,2"]
+|===
+| Feature | Property | Default Value
+
+|Color
+|`--vaadin-input-field-label-color`
+|`--lumo-secondary-text-color`
+
+|Focused color
+|`--vaadin-input-field-focused-label-color`
+|`--lumo-primary-text-color`
+
+|Hovered color
+|`--vaadin-input-field-hovered-label-color`
+|`--lumo-body-text-color`
+
+|Font size
+|`--vaadin-input-field-label-font-size`
+|`--lumo-font-size-s`
+
+|Font weight
+|`--vaadin-input-field-label-font-weight`
+|`500`
+
+|===
+
+=== Helper
+
+[cols="1,2,2"]
+|===
+| Feature | Property | Default Value
+
+|Font size
+|`--vaadin-input-field-helper-font-size`
+|`--lumo-font-size-xs`
+
+|Font weight
+|`--vaadin-input-field-helper-font-weight`
+|`400`
+
+|Color
+|`--vaadin-input-field-helper-color`
+|`--lumo-secondary-text-color`
+
+|Top margin
+|`--vaadin-input-field-helper-spacing`
+|`0.4em`
+
+|===
+
+=== Error Message
+
+[cols="1,2,2"]
+|===
+| Feature | Property | Default Value
+
+|Font size
+|`--vaadin-input-field-error-font-size`
+|`--lumo-font-size-xs`
+
+|Font weight
+|`--vaadin-input-field-error-font-weight`
+|`400`
+
+|Color
+|`--vaadin-input-field-error-color`
+|`--lumo-error-text-color`
+
+|===
+// end::label-helper-error[]
+
+
+// tag::input-icons[]
+=== Icons
+[cols="1,2,2"]
+|===
+| Feature | Property | Default Value
+
+|Font size
+|`--vaadin-input-field-icon-font-size`
+|`--lumo-icon-size-m`
+
+|Color
+|`--vaadin-input-field-icon-color`
+|`--lumo-contrast-60pct`
+
+|===
+// end::input-icons[]