feat: add setRole to Dialog and Popover, deprecate setOverlayRole (#7796)

web-padawan · sissbruecker · web-flow · commit 2919f9564cc0 · 2025-08-04T17:00:19.000+02:00
* feat: add setRole to Dialog and Popover, deprecate setOverlayRole

* Update vaadin-popover-flow-parent/vaadin-popover-flow/src/main/java/com/vaadin/flow/component/popover/Popover.java

Co-authored-by: Sascha Ißbrücker &lt;sissbruecker@vaadin.com&gt;

---------

Co-authored-by: Sascha Ißbrücker &lt;sissbruecker@vaadin.com&gt;
diff --git a/vaadin-dialog-flow-parent/vaadin-dialog-flow/src/main/java/com/vaadin/flow/component/dialog/Dialog.java b/vaadin-dialog-flow-parent/vaadin-dialog-flow/src/main/java/com/vaadin/flow/component/dialog/Dialog.java
@@ -125,7 +125,7 @@ public Dialog() {
             setLeft(event.getLeft());
         });
 
-        setOverlayRole("dialog");
+        setRole("dialog");
 
         // Initialize auto-add behavior
         new OverlayAutoAddController<>(this, this::isModal);
@@ -1099,26 +1099,52 @@ protected void onAttach(AttachEvent attachEvent) {
         registerClientCloseHandler();
     }
 
+    /**
+     * Sets the ARIA role for the dialog element, used by screen readers.
+     *
+     * @param role
+     *            the role to set
+     */
+    public void setRole(String role) {
+        Objects.requireNonNull(role, "Role cannot be null");
+
+        getElement().setProperty("role", role);
+    }
+
     /**
      * Sets the ARIA role for the overlay element, used by screen readers.
      *
      * @param role
      *            the role to set
+     * @deprecated Use {@link #setRole(String)} instead
      */
+    @Deprecated(since = "25.0", forRemoval = true)
     public void setOverlayRole(String role) {
         Objects.requireNonNull(role, "Role cannot be null");
 
-        getElement().setProperty("overlayRole", role);
+        setRole(role);
+    }
+
+    /**
+     * Gets the ARIA role for the overlay element, used by screen readers.
+     * Defaults to {@code dialog}.
+     *
+     * @return the role
+     */
+    public String getRole() {
+        return getElement().getProperty("role");
     }
 
     /**
      * Gets the ARIA role for the overlay element, used by screen readers.
      * Defaults to {@code dialog}.
      *
      * @return the role
+     * @deprecated Use {@link #getRole()} instead
      */
+    @Deprecated(since = "25.0", forRemoval = true)
     public String getOverlayRole() {
-        return getElement().getProperty("overlayRole");
+        return getRole();
     }
 
     /**
diff --git a/vaadin-dialog-flow-parent/vaadin-dialog-flow/src/test/java/com/vaadin/flow/component/dialog/DialogTest.java b/vaadin-dialog-flow-parent/vaadin-dialog-flow/src/test/java/com/vaadin/flow/component/dialog/DialogTest.java
@@ -193,22 +193,23 @@ public void isModal_trueByDefault() {
     }
 
     @Test
-    public void getOverlayRole_defaultDialog() {
+    public void getRole_defaultDialog() {
         Dialog dialog = new Dialog();
 
+        Assert.assertEquals("dialog", dialog.getRole());
         Assert.assertEquals("dialog", dialog.getOverlayRole());
-        Assert.assertEquals("dialog",
-                dialog.getElement().getProperty("overlayRole"));
+        Assert.assertEquals("dialog", dialog.getElement().getProperty("role"));
     }
 
     @Test
     public void setOverlayRole_getOverlayRole() {
         Dialog dialog = new Dialog();
         dialog.setOverlayRole("alertdialog");
 
+        Assert.assertEquals("alertdialog", dialog.getRole());
         Assert.assertEquals("alertdialog", dialog.getOverlayRole());
         Assert.assertEquals("alertdialog",
-                dialog.getElement().getProperty("overlayRole"));
+                dialog.getElement().getProperty("role"));
     }
 
     @Test(expected = NullPointerException.class)
@@ -217,6 +218,23 @@ public void setOverlayRole_null_throws() {
         dialog.setOverlayRole(null);
     }
 
+    @Test
+    public void setRole_getRole() {
+        Dialog dialog = new Dialog();
+        dialog.setRole("alertdialog");
+
+        Assert.assertEquals("alertdialog", dialog.getRole());
+        Assert.assertEquals("alertdialog", dialog.getOverlayRole());
+        Assert.assertEquals("alertdialog",
+                dialog.getElement().getProperty("role"));
+    }
+
+    @Test(expected = NullPointerException.class)
+    public void setRole_null_throws() {
+        Dialog dialog = new Dialog();
+        dialog.setRole(null);
+    }
+
     @Test
     public void setModal_dialogCanBeModeless() {
         Dialog dialog = new Dialog();
diff --git a/vaadin-popover-flow-parent/vaadin-popover-flow/src/main/java/com/vaadin/flow/component/popover/Popover.java b/vaadin-popover-flow-parent/vaadin-popover-flow/src/main/java/com/vaadin/flow/component/popover/Popover.java
@@ -78,7 +78,7 @@ public Popover() {
         getElement().setProperty("opened", false);
 
         updateTrigger();
-        setOverlayRole("dialog");
+        setRole("dialog");
     }
 
     /**
@@ -344,26 +344,52 @@ public boolean isAutofocus() {
         return getElement().getProperty("autofocus", false);
     }
 
+    /**
+     * Sets the ARIA role for the popover element, used by screen readers.
+     *
+     * @param role
+     *            the role to set
+     */
+    public void setRole(String role) {
+        Objects.requireNonNull(role, "Role cannot be null");
+
+        getElement().setProperty("role", role);
+    }
+
     /**
      * Sets the ARIA role for the overlay element, used by screen readers.
      *
      * @param role
      *            the role to set
+     * @deprecated Use {@link #setRole(String)} instead
      */
+    @Deprecated(since = "25.0", forRemoval = true)
     public void setOverlayRole(String role) {
         Objects.requireNonNull(role, "Role cannot be null");
 
-        getElement().setProperty("overlayRole", role);
+        setRole(role);
+    }
+
+    /**
+     * Gets the ARIA role for the popover element, used by screen readers.
+     * Defaults to {@code dialog}.
+     *
+     * @return the role
+     */
+    public String getRole() {
+        return getElement().getProperty("role");
     }
 
     /**
-     * Gets the ARIA role for the overlay element, used by screen readers.
+     * Gets the ARIA role for the popover element, used by screen readers.
      * Defaults to {@code dialog}.
      *
      * @return the role
+     * @deprecated Use {@link #getRole()} instead
      */
+    @Deprecated(since = "25.0", forRemoval = true)
     public String getOverlayRole() {
-        return getElement().getProperty("overlayRole");
+        return getRole();
     }
 
     /**
diff --git a/vaadin-popover-flow-parent/vaadin-popover-flow/src/test/java/com/vaadin/flow/component/popover/PopoverTest.java b/vaadin-popover-flow-parent/vaadin-popover-flow/src/test/java/com/vaadin/flow/component/popover/PopoverTest.java
@@ -232,26 +232,44 @@ public void setAriaLabelledBy_getAriaLabelledBy() {
     }
 
     @Test
-    public void getOverlayRole_defaultDialog() {
+    public void getRole_defaultDialog() {
+        Popover popover = new Popover();
+
+        Assert.assertEquals("dialog", popover.getRole());
         Assert.assertEquals("dialog", popover.getOverlayRole());
-        Assert.assertEquals("dialog",
-                popover.getElement().getProperty("overlayRole"));
+        Assert.assertEquals("dialog", popover.getElement().getProperty("role"));
     }
 
     @Test
     public void setOverlayRole_getOverlayRole() {
         popover.setOverlayRole("alertdialog");
 
+        Assert.assertEquals("alertdialog", popover.getRole());
         Assert.assertEquals("alertdialog", popover.getOverlayRole());
         Assert.assertEquals("alertdialog",
-                popover.getElement().getProperty("overlayRole"));
+                popover.getElement().getProperty("role"));
     }
 
     @Test(expected = NullPointerException.class)
     public void setOverlayRole_null_throws() {
         popover.setOverlayRole(null);
     }
 
+    @Test
+    public void setRole_getRole() {
+        popover.setRole("alertdialog");
+
+        Assert.assertEquals("alertdialog", popover.getRole());
+        Assert.assertEquals("alertdialog", popover.getOverlayRole());
+        Assert.assertEquals("alertdialog",
+                popover.getElement().getProperty("role"));
+    }
+
+    @Test(expected = NullPointerException.class)
+    public void setRole_null_throws() {
+        popover.setRole(null);
+    }
+
     @Test
     public void setModal_isModal() {
         Assert.assertFalse(popover.isModal());
