feat: add HasAriaDescription to field components (#9811)

This PR adds the `HasAriaDescription` mixin interface to all field
components that implement `HasAriaLabel`, overriding
`setAriaDescribedBy` / `getAriaDescribedBy` to map to the
`accessibleDescriptionRef` property, which propagates the reference to
the input element (the default implementation sets attributes on the
host element instead). This follows the same pattern as `accessibleName`
/ `accessibleNameRef`.

DateTimePicker is left out because it doesn't implement `HasAriaLabel`,
`HasPrefix` or `HasSuffix`.

Part of vaadin/web-components#11975

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: vursen

vaadin-checkbox-flow-parent/vaadin-checkbox-flow/src/main/java/com/vaadin/flow/component/checkbox/Checkbox.java

@@ -25,6 +25,7 @@
 import com.vaadin.flow.component.ClickNotifier;
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.Focusable;
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.HasAriaLabel;
 import com.vaadin.flow.component.Synchronize;
 import com.vaadin.flow.component.Tag;
@@ -85,8 +86,9 @@
 @NpmPackage(value = "@vaadin/checkbox", version = "25.3.0-alpha8")
 @JsModule("@vaadin/checkbox/src/vaadin-checkbox.js")
 public class Checkbox extends AbstractSinglePropertyField<Checkbox, Boolean>
-        implements ClickNotifier<Checkbox>, Focusable<Checkbox>, HasAriaLabel,
-        HasValidationProperties, HasValidator<Boolean>,
+        implements ClickNotifier<Checkbox>, Focusable<Checkbox>,
+        HasAriaDescription, HasAriaLabel, HasValidationProperties,
+        HasValidator<Boolean>,
         InputField<AbstractField.ComponentValueChangeEvent<Checkbox, Boolean>, Boolean>,
         HasThemeVariant<CheckboxVariant> {
 
@@ -322,6 +324,23 @@ public Optional<String> getAriaLabelledBy() {
                 .ofNullable(getElement().getProperty("accessibleNameRef"));
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * The referenced elements are announced in addition to the helper text and
+     * the error message.
+     */
+    @Override
+    public void setAriaDescribedBy(String ariaDescribedBy) {
+        getElement().setProperty("accessibleDescriptionRef", ariaDescribedBy);
+    }
+
+    @Override
+    public Optional<String> getAriaDescribedBy() {
+        return Optional.ofNullable(
+                getElement().getProperty("accessibleDescriptionRef"));
+    }
+
     /**
      * Set the checkbox to be input focused when the page loads.
      *

vaadin-checkbox-flow-parent/vaadin-checkbox-flow/src/main/java/com/vaadin/flow/component/checkbox/CheckboxGroup.java

@@ -33,6 +33,7 @@
 import com.vaadin.flow.component.AbstractSinglePropertyField;
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.ComponentUtil;
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.HasAriaLabel;
 import com.vaadin.flow.component.ItemLabelGenerator;
 import com.vaadin.flow.component.Tag;
@@ -116,8 +117,8 @@
 @JsModule("@vaadin/checkbox-group/src/vaadin-checkbox-group.js")
 public class CheckboxGroup<T>
         extends AbstractSinglePropertyField<CheckboxGroup<T>, Set<T>>
-        implements HasAriaLabel, HasDataView<T, Void, CheckboxGroupDataView<T>>,
-        HasItemComponents<T>,
+        implements HasAriaDescription, HasAriaLabel,
+        HasDataView<T, Void, CheckboxGroupDataView<T>>, HasItemComponents<T>,
         InputField<AbstractField.ComponentValueChangeEvent<CheckboxGroup<T>, Set<T>>, Set<T>>,
         HasListDataView<T, CheckboxGroupListDataView<T>>,
         HasThemeVariant<CheckboxGroupVariant>, HasValidationProperties,
@@ -663,6 +664,23 @@ public Optional<String> getAriaLabelledBy() {
                 .ofNullable(getElement().getProperty("accessibleNameRef"));
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * The referenced elements are announced in addition to the helper text and
+     * the error message.
+     */
+    @Override
+    public void setAriaDescribedBy(String ariaDescribedBy) {
+        getElement().setProperty("accessibleDescriptionRef", ariaDescribedBy);
+    }
+
+    @Override
+    public Optional<String> getAriaDescribedBy() {
+        return Optional.ofNullable(
+                getElement().getProperty("accessibleDescriptionRef"));
+    }
+
     /**
      * Sets whether the user is required to select at least one checkbox. When
      * required, an indicator appears next to the label and the field

vaadin-checkbox-flow-parent/vaadin-checkbox-flow/src/main/java/com/vaadin/flow/component/checkbox/Switch.java

@@ -27,6 +27,7 @@
 import com.vaadin.flow.component.ClickNotifier;
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.Focusable;
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.HasAriaLabel;
 import com.vaadin.flow.component.Tag;
 import com.vaadin.flow.component.UI;
@@ -83,8 +84,8 @@
 @NpmPackage(value = "@vaadin/switch", version = "25.3.0-alpha8")
 @JsModule("@vaadin/switch/src/vaadin-switch.js")
 public class Switch extends AbstractSinglePropertyField<Switch, Boolean>
-        implements ClickNotifier<Switch>, Focusable<Switch>, HasAriaLabel,
-        HasValidationProperties, HasValidator<Boolean>,
+        implements ClickNotifier<Switch>, Focusable<Switch>, HasAriaDescription,
+        HasAriaLabel, HasValidationProperties, HasValidator<Boolean>,
         InputField<AbstractField.ComponentValueChangeEvent<Switch, Boolean>, Boolean>,
         HasThemeVariant<SwitchVariant> {
 
@@ -320,6 +321,23 @@ public Optional<String> getAriaLabelledBy() {
                 .ofNullable(getElement().getProperty("accessibleNameRef"));
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * The referenced elements are announced in addition to the helper text and
+     * the error message.
+     */
+    @Override
+    public void setAriaDescribedBy(String ariaDescribedBy) {
+        getElement().setProperty("accessibleDescriptionRef", ariaDescribedBy);
+    }
+
+    @Override
+    public Optional<String> getAriaDescribedBy() {
+        return Optional.ofNullable(
+                getElement().getProperty("accessibleDescriptionRef"));
+    }
+
     /**
      * Set the switch to be input focused when the page loads.
      *

vaadin-checkbox-flow-parent/vaadin-checkbox-flow/src/test/java/com/vaadin/flow/component/checkbox/tests/CheckboxGroupTest.java

@@ -32,6 +32,7 @@
 
 import com.vaadin.flow.component.AbstractField;
 import com.vaadin.flow.component.Component;
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.HasAriaLabel;
 import com.vaadin.flow.component.HasValue;
 import com.vaadin.flow.component.HasValue.ValueChangeEvent;
@@ -625,6 +626,28 @@ void setAriaLabelledBy() {
         Assertions.assertTrue(group.getAriaLabelledBy().isEmpty());
     }
 
+    @Test
+    void implementHasAriaDescription() {
+        Assertions.assertTrue(
+                HasAriaDescription.class.isAssignableFrom(CheckboxGroup.class));
+    }
+
+    @Test
+    void setAriaDescribedBy() {
+        CheckboxGroup<String> group = new CheckboxGroup<>();
+        group.setAriaDescribedBy("description-id");
+
+        Assertions.assertEquals("description-id",
+                group.getElement().getProperty("accessibleDescriptionRef"));
+        Assertions.assertEquals("description-id",
+                group.getAriaDescribedBy().get());
+
+        group.setAriaDescribedBy((String) null);
+        Assertions.assertNull(
+                group.getElement().getProperty("accessibleDescriptionRef"));
+        Assertions.assertTrue(group.getAriaDescribedBy().isEmpty());
+    }
+
     @Test
     void implementsInputField() {
         CheckboxGroup<String> field = new CheckboxGroup<String>();

vaadin-checkbox-flow-parent/vaadin-checkbox-flow/src/test/java/com/vaadin/flow/component/checkbox/tests/CheckboxUnitTest.java

@@ -22,6 +22,7 @@
 
 import com.vaadin.flow.component.AbstractField;
 import com.vaadin.flow.component.Component;
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.HasAriaLabel;
 import com.vaadin.flow.component.checkbox.Checkbox;
 import com.vaadin.flow.component.shared.HasThemeVariant;
@@ -147,6 +148,28 @@ void setAriaLabelledBy() {
         Assertions.assertTrue(checkbox.getAriaLabelledBy().isEmpty());
     }
 
+    @Test
+    void implementHasAriaDescription() {
+        Checkbox checkbox = new Checkbox();
+        Assertions.assertTrue(checkbox instanceof HasAriaDescription);
+    }
+
+    @Test
+    void setAriaDescribedBy() {
+        Checkbox checkbox = new Checkbox();
+        checkbox.setAriaDescribedBy("description-id");
+
+        Assertions.assertEquals("description-id",
+                checkbox.getElement().getProperty("accessibleDescriptionRef"));
+        Assertions.assertEquals("description-id",
+                checkbox.getAriaDescribedBy().get());
+
+        checkbox.setAriaDescribedBy((String) null);
+        Assertions.assertNull(
+                checkbox.getElement().getProperty("accessibleDescriptionRef"));
+        Assertions.assertTrue(checkbox.getAriaDescribedBy().isEmpty());
+    }
+
     @Test
     void implementsInputField() {
         Checkbox field = new Checkbox();

vaadin-checkbox-flow-parent/vaadin-checkbox-flow/src/test/java/com/vaadin/flow/component/checkbox/tests/SwitchTest.java

@@ -19,6 +19,7 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.checkbox.Switch;
 import com.vaadin.flow.component.shared.HasThemeVariant;
 import com.vaadin.tests.MockUIExtension;
@@ -73,4 +74,26 @@ void implementsHasThemeVariant() {
         Assertions.assertTrue(
                 HasThemeVariant.class.isAssignableFrom(Switch.class));
     }
+
+    @Test
+    void implementsHasAriaDescription() {
+        Assertions.assertTrue(
+                HasAriaDescription.class.isAssignableFrom(Switch.class));
+    }
+
+    @Test
+    void setAriaDescribedBy() {
+        Switch field = new Switch();
+        field.setAriaDescribedBy("description-id");
+
+        Assertions.assertEquals("description-id",
+                field.getElement().getProperty("accessibleDescriptionRef"));
+        Assertions.assertEquals("description-id",
+                field.getAriaDescribedBy().get());
+
+        field.setAriaDescribedBy((String) null);
+        Assertions.assertNull(
+                field.getElement().getProperty("accessibleDescriptionRef"));
+        Assertions.assertTrue(field.getAriaDescribedBy().isEmpty());
+    }
 }

vaadin-combo-box-flow-parent/vaadin-combo-box-flow/src/main/java/com/vaadin/flow/component/combobox/ComboBoxBase.java

@@ -37,6 +37,7 @@
 import com.vaadin.flow.component.DomEvent;
 import com.vaadin.flow.component.EventData;
 import com.vaadin.flow.component.Focusable;
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.HasAriaLabel;
 import com.vaadin.flow.component.HasPlaceholder;
 import com.vaadin.flow.component.HasTheme;
@@ -91,9 +92,10 @@
  * @since 23.2
  */
 public abstract class ComboBoxBase<TComponent extends ComboBoxBase<TComponent, TItem, TValue>, TItem, TValue>
-        extends AbstractSinglePropertyField<TComponent, TValue> implements
-        Focusable<TComponent>, HasAllowedCharPattern, HasAriaLabel, HasAutoOpen,
-        HasClearButton, HasDataView<TItem, String, ComboBoxDataView<TItem>>,
+        extends AbstractSinglePropertyField<TComponent, TValue>
+        implements Focusable<TComponent>, HasAllowedCharPattern,
+        HasAriaDescription, HasAriaLabel, HasAutoOpen, HasClearButton,
+        HasDataView<TItem, String, ComboBoxDataView<TItem>>,
         InputField<AbstractField.ComponentValueChangeEvent<TComponent, TValue>, TValue>,
         HasLazyDataView<TItem, String, ComboBoxLazyDataView<TItem>>,
         HasListDataView<TItem, ComboBoxListDataView<TItem>>, HasTheme,
@@ -461,6 +463,23 @@ public Optional<String> getAriaLabelledBy() {
                 .ofNullable(getElement().getProperty("accessibleNameRef"));
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * The referenced elements are announced in addition to the helper text and
+     * the error message.
+     */
+    @Override
+    public void setAriaDescribedBy(String ariaDescribedBy) {
+        getElement().setProperty("accessibleDescriptionRef", ariaDescribedBy);
+    }
+
+    @Override
+    public Optional<String> getAriaDescribedBy() {
+        return Optional.ofNullable(
+                getElement().getProperty("accessibleDescriptionRef"));
+    }
+
     /**
      * Sets the item label generator that is used to produce the strings shown
      * in the combo box for each item. By default,

vaadin-combo-box-flow-parent/vaadin-combo-box-flow/src/test/java/com/vaadin/flow/component/combobox/ComboBoxBaseTest.java

@@ -25,6 +25,7 @@
 import org.mockito.Mockito;
 
 import com.vaadin.flow.component.Focusable;
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.HasAriaLabel;
 import com.vaadin.flow.component.HasLabel;
 import com.vaadin.flow.component.HasPlaceholder;
@@ -77,6 +78,14 @@ void implementsHasAriaLabel() {
                 "ComboBox should support setting aria-label and aria-labelledby");
     }
 
+    @Test
+    void implementsHasAriaDescription() {
+        Assertions.assertTrue(
+                HasAriaDescription.class.isAssignableFrom(
+                        createComboBox(String.class).getClass()),
+                "ComboBox should support setting aria-describedby");
+    }
+
     @Test
     void implementsHasAllowedCharPattern() {
         Assertions.assertTrue(
@@ -375,4 +384,20 @@ void setAriaLabelledBy() {
         comboBox.setAriaLabelledBy((String) null);
         Assertions.assertTrue(comboBox.getAriaLabelledBy().isEmpty());
     }
+
+    @Test
+    void setAriaDescribedBy() {
+        ComboBoxBase<?, String, ?> comboBox = createComboBox(String.class);
+
+        comboBox.setAriaDescribedBy("description-id");
+        Assertions.assertEquals("description-id",
+                comboBox.getElement().getProperty("accessibleDescriptionRef"));
+        Assertions.assertEquals("description-id",
+                comboBox.getAriaDescribedBy().get());
+
+        comboBox.setAriaDescribedBy((String) null);
+        Assertions.assertNull(
+                comboBox.getElement().getProperty("accessibleDescriptionRef"));
+        Assertions.assertTrue(comboBox.getAriaDescribedBy().isEmpty());
+    }
 }

vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java

@@ -37,6 +37,7 @@
 import com.vaadin.flow.component.ComponentEvent;
 import com.vaadin.flow.component.ComponentEventListener;
 import com.vaadin.flow.component.Focusable;
+import com.vaadin.flow.component.HasAriaDescription;
 import com.vaadin.flow.component.HasAriaLabel;
 import com.vaadin.flow.component.HasPlaceholder;
 import com.vaadin.flow.component.HasValue;
@@ -134,8 +135,8 @@
 @NpmPackage(value = "date-fns", version = "4.1.0")
 public class DatePicker
         extends AbstractSinglePropertyField<DatePicker, LocalDate>
-        implements Focusable<DatePicker>, HasAllowedCharPattern, HasAriaLabel,
-        HasAutoOpen, HasClearButton,
+        implements Focusable<DatePicker>, HasAllowedCharPattern,
+        HasAriaDescription, HasAriaLabel, HasAutoOpen, HasClearButton,
         InputField<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>, LocalDate>,
         HasPrefix, HasThemeVariant<DatePickerVariant>, HasValidationProperties,
         HasValidator<LocalDate>, HasPlaceholder {
@@ -572,6 +573,23 @@ public Optional<String> getAriaLabelledBy() {
                 .ofNullable(getElement().getProperty("accessibleNameRef"));
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * The referenced elements are announced in addition to the helper text and
+     * the error message.
+     */
+    @Override
+    public void setAriaDescribedBy(String ariaDescribedBy) {
+        getElement().setProperty("accessibleDescriptionRef", ariaDescribedBy);
+    }
+
+    @Override
+    public Optional<String> getAriaDescribedBy() {
+        return Optional.ofNullable(
+                getElement().getProperty("accessibleDescriptionRef"));
+    }
+
     @Override
     protected void onAttach(AttachEvent attachEvent) {
         super.onAttach(attachEvent);