Simplify and clarify WAI-ARIA API (#11659)

Change-Id: I8daf3f377d4d9f2c2f774781e0c68f550d5c86e0

13 files changed, 64 insertions, 74 deletions

diff --git a/client/src/com/vaadin/client/VCaption.java b/client/src/com/vaadin/client/VCaption.java
index 787b650f3f..591aeaa436 100644
--- a/client/src/com/vaadin/client/VCaption.java
+++ b/client/src/com/vaadin/client/VCaption.java
@@ -23,8 +23,8 @@ import com.google.gwt.user.client.Event;
 import com.google.gwt.user.client.ui.HTML;
 import com.vaadin.client.communication.StateChangeEvent;
 import com.vaadin.client.ui.AbstractFieldConnector;
-import com.vaadin.client.ui.AriaHelper;
 import com.vaadin.client.ui.Icon;
+import com.vaadin.client.ui.aria.AriaHelper;
 import com.vaadin.shared.AbstractComponentState;
 import com.vaadin.shared.AbstractFieldState;
 import com.vaadin.shared.ComponentConstants;
diff --git a/client/src/com/vaadin/client/ui/VCheckBox.java b/client/src/com/vaadin/client/ui/VCheckBox.java
index 4c592d52a1..bb49dd7f0a 100644
--- a/client/src/com/vaadin/client/ui/VCheckBox.java
+++ b/client/src/com/vaadin/client/ui/VCheckBox.java
@@ -22,6 +22,9 @@ import com.google.gwt.user.client.Event;
 import com.vaadin.client.ApplicationConnection;
 import com.vaadin.client.Util;
 import com.vaadin.client.VTooltip;
+import com.vaadin.client.ui.aria.AriaHelper;
+import com.vaadin.client.ui.aria.HandlesAriaInvalid;
+import com.vaadin.client.ui.aria.HandlesAriaRequired;
 
 public class VCheckBox extends com.google.gwt.user.client.ui.CheckBox implements
         Field, HandlesAriaInvalid, HandlesAriaRequired {
@@ -80,12 +83,12 @@ public class VCheckBox extends com.google.gwt.user.client.ui.CheckBox implements
     }
 
     @Override
-    public void setRequired(boolean required) {
+    public void setAriaRequired(boolean required) {
         AriaHelper.handleInputRequired(getCheckBoxElement(), required);
     }
 
     @Override
-    public void setInvalid(boolean invalid) {
+    public void setAriaInvalid(boolean invalid) {
         AriaHelper.handleInputInvalid(getCheckBoxElement(), invalid);
     }
 }
diff --git a/client/src/com/vaadin/client/ui/VFilterSelect.java b/client/src/com/vaadin/client/ui/VFilterSelect.java
index d74bb6c7a2..3ad3d93abe 100644
--- a/client/src/com/vaadin/client/ui/VFilterSelect.java
+++ b/client/src/com/vaadin/client/ui/VFilterSelect.java
@@ -67,6 +67,9 @@ import com.vaadin.client.Focusable;
 import com.vaadin.client.UIDL;
 import com.vaadin.client.Util;
 import com.vaadin.client.VConsole;
+import com.vaadin.client.ui.aria.AriaHelper;
+import com.vaadin.client.ui.aria.HandlesAriaInvalid;
+import com.vaadin.client.ui.aria.HandlesAriaRequired;
 import com.vaadin.client.ui.menubar.MenuBar;
 import com.vaadin.client.ui.menubar.MenuItem;
 import com.vaadin.shared.AbstractComponentState;
@@ -1835,12 +1838,12 @@ public class VFilterSelect extends Composite implements Field, KeyDownHandler,
     }
 
     @Override
-    public void setRequired(boolean required) {
+    public void setAriaRequired(boolean required) {
         AriaHelper.handleInputRequired(tb, required);
     }
 
     @Override
-    public void setInvalid(boolean invalid) {
+    public void setAriaInvalid(boolean invalid) {
         AriaHelper.handleInputInvalid(tb, invalid);
     }
 }
diff --git a/client/src/com/vaadin/client/ui/VFormLayout.java b/client/src/com/vaadin/client/ui/VFormLayout.java
index 37a2541aba..b2dc13178e 100644
--- a/client/src/com/vaadin/client/ui/VFormLayout.java
+++ b/client/src/com/vaadin/client/ui/VFormLayout.java
@@ -35,6 +35,7 @@ import com.vaadin.client.ComponentConnector;
 import com.vaadin.client.Focusable;
 import com.vaadin.client.StyleConstants;
 import com.vaadin.client.VTooltip;
+import com.vaadin.client.ui.aria.AriaHelper;
 import com.vaadin.shared.AbstractComponentState;
 import com.vaadin.shared.ComponentConstants;
 import com.vaadin.shared.ui.ComponentStateUtil;
diff --git a/client/src/com/vaadin/client/ui/VPopupCalendar.java b/client/src/com/vaadin/client/ui/VPopupCalendar.java
index 87dd4061a7..410217a0dd 100644
--- a/client/src/com/vaadin/client/ui/VPopupCalendar.java
+++ b/client/src/com/vaadin/client/ui/VPopupCalendar.java
@@ -44,6 +44,7 @@ import com.vaadin.client.BrowserInfo;
 import com.vaadin.client.VConsole;
 import com.vaadin.client.ui.VCalendarPanel.FocusOutListener;
 import com.vaadin.client.ui.VCalendarPanel.SubmitListener;
+import com.vaadin.client.ui.aria.AriaHelper;
 import com.vaadin.shared.ui.datefield.PopupDateFieldState;
 import com.vaadin.shared.ui.datefield.Resolution;
 
@@ -100,10 +101,10 @@ public class VPopupCalendar extends VTextualDate implements Field,
         descriptionForAssisitveDevicesElement = DOM.createDiv();
         descriptionForAssisitveDevicesElement
                 .setInnerText(PopupDateFieldState.DESCRIPTION_FOR_ASSISTIVE_DEVICES);
-        AriaHelper.ensureUniqueId(descriptionForAssisitveDevicesElement);
+        AriaHelper.ensureHasId(descriptionForAssisitveDevicesElement);
         Id.of(descriptionForAssisitveDevicesElement);
-        AriaHelper
-                .visibleForAssistiveDevicesOnly(descriptionForAssisitveDevicesElement);
+        AriaHelper.setVisibleForAssistiveDevicesOnly(
+                descriptionForAssisitveDevicesElement, true);
         DOM.appendChild(getElement(), descriptionForAssisitveDevicesElement);
 
         calendar = GWT.create(VCalendarPanel.class);
@@ -144,7 +145,8 @@ public class VPopupCalendar extends VTextualDate implements Field,
         FlowPanel wrapper = new FlowPanel();
         selectedDate = new Label();
         selectedDate.setStyleName(getStylePrimaryName() + "-selecteddate");
-        AriaHelper.visibleForAssistiveDevicesOnly(selectedDate.getElement());
+        AriaHelper.setVisibleForAssistiveDevicesOnly(selectedDate.getElement(),
+                true);
 
         Roles.getTextboxRole().setAriaLiveProperty(selectedDate.getElement(),
                 LiveValue.ASSERTIVE);
@@ -238,7 +240,11 @@ public class VPopupCalendar extends VTextualDate implements Field,
 
     @Override
     public void bindAriaCaption(Element captionElement) {
-        captionId = captionElement.getId();
+        if (captionElement == null) {
+            captionId = null;
+        } else {
+            captionId = captionElement.getId();
+        }
 
         if (isTextFieldEnabled()) {
             super.bindAriaCaption(captionElement);
@@ -272,18 +278,6 @@ public class VPopupCalendar extends VTextualDate implements Field,
         }
     }
 
-    @Override
-    public void clearAriaCaption() {
-        captionId = null;
-        if (isTextFieldEnabled()) {
-            super.clearAriaCaption();
-        } else {
-            AriaHelper.bindCaption(calendarToggle, null);
-        }
-
-        handleAriaAttributes();
-    }
-
     /*
      * (non-Javadoc)
      * 
diff --git a/client/src/com/vaadin/client/ui/VTextualDate.java b/client/src/com/vaadin/client/ui/VTextualDate.java
index 92cc81605c..cdfd8d00c2 100644
--- a/client/src/com/vaadin/client/ui/VTextualDate.java
+++ b/client/src/com/vaadin/client/ui/VTextualDate.java
@@ -31,6 +31,10 @@ import com.vaadin.client.Focusable;
 import com.vaadin.client.LocaleNotLoadedException;
 import com.vaadin.client.LocaleService;
 import com.vaadin.client.VConsole;
+import com.vaadin.client.ui.aria.AriaHelper;
+import com.vaadin.client.ui.aria.HandlesAriaCaption;
+import com.vaadin.client.ui.aria.HandlesAriaInvalid;
+import com.vaadin.client.ui.aria.HandlesAriaRequired;
 import com.vaadin.shared.EventId;
 import com.vaadin.shared.ui.datefield.Resolution;
 
@@ -161,17 +165,12 @@ public class VTextualDate extends VDateField implements Field, ChangeHandler,
     }
 
     @Override
-    public void clearAriaCaption() {
-        AriaHelper.bindCaption(text, null);
-    }
-
-    @Override
-    public void setRequired(boolean required) {
+    public void setAriaRequired(boolean required) {
         AriaHelper.handleInputRequired(text, required);
     }
 
     @Override
-    public void setInvalid(boolean invalid) {
+    public void setAriaInvalid(boolean invalid) {
         AriaHelper.handleInputInvalid(text, invalid);
     }
 
diff --git a/client/src/com/vaadin/client/ui/VTree.java b/client/src/com/vaadin/client/ui/VTree.java
index 9ad8e5be7c..e08b483c8c 100644
--- a/client/src/com/vaadin/client/ui/VTree.java
+++ b/client/src/com/vaadin/client/ui/VTree.java
@@ -60,6 +60,8 @@ import com.vaadin.client.ConnectorMap;
 import com.vaadin.client.MouseEventDetailsBuilder;
 import com.vaadin.client.UIDL;
 import com.vaadin.client.Util;
+import com.vaadin.client.ui.aria.AriaHelper;
+import com.vaadin.client.ui.aria.HandlesAriaCaption;
 import com.vaadin.client.ui.dd.DDUtil;
 import com.vaadin.client.ui.dd.VAbstractDropHandler;
 import com.vaadin.client.ui.dd.VAcceptCallback;
@@ -2212,10 +2214,4 @@ public class VTree extends FocusElementPanel implements VHasDropHandler,
     public void bindAriaCaption(Element captionElement) {
         AriaHelper.bindCaption(body, captionElement);
     }
-
-    @Override
-    public void clearAriaCaption() {
-        AriaHelper.bindCaption(body, null);
-    }
-
 }
diff --git a/client/src/com/vaadin/client/ui/AriaHelper.java b/client/src/com/vaadin/client/ui/aria/AriaHelper.java
index 450b25c8da..0ff58cf510 100644
--- a/client/src/com/vaadin/client/ui/AriaHelper.java
+++ b/client/src/com/vaadin/client/ui/aria/AriaHelper.java
@@ -14,7 +14,7 @@
  * the License.
  */
 
-package com.vaadin.client.ui;
+package com.vaadin.client.ui.aria;
 
 import com.google.gwt.aria.client.Id;
 import com.google.gwt.aria.client.InvalidValue;
@@ -44,15 +44,15 @@ public class AriaHelper {
         if (widget instanceof HandlesAriaCaption) {
             // Let the widget handle special cases itself
             if (captionElement == null) {
-                ((HandlesAriaCaption) widget).clearAriaCaption();
+                ((HandlesAriaCaption) widget).bindAriaCaption(null);
             } else {
-                ensureUniqueId(captionElement);
+                ensureHasId(captionElement);
                 ((HandlesAriaCaption) widget).bindAriaCaption(captionElement);
             }
         } else if (captionElement != null) {
             // Handle the default case
-            ensureUniqueId(captionElement);
-            String ownerId = ensureUniqueId(widget.getElement());
+            ensureHasId(captionElement);
+            String ownerId = ensureHasId(widget.getElement());
             captionElement.setAttribute("for", ownerId);
 
             Roles.getTextboxRole().setAriaLabelledbyProperty(
@@ -87,7 +87,7 @@ public class AriaHelper {
         assert widget != null : "Valid Widget required";
 
         if (widget instanceof HandlesAriaRequired) {
-            ((HandlesAriaRequired) widget).setRequired(required);
+            ((HandlesAriaRequired) widget).setAriaRequired(required);
         } else {
             handleInputRequired(widget.getElement(), required);
         }
@@ -123,7 +123,7 @@ public class AriaHelper {
         assert widget != null : "Valid Widget required";
 
         if (widget instanceof HandlesAriaInvalid) {
-            ((HandlesAriaInvalid) widget).setInvalid(invalid);
+            ((HandlesAriaInvalid) widget).setAriaInvalid(invalid);
         } else {
             handleInputInvalid(widget.getElement(), invalid);
         }
@@ -155,7 +155,7 @@ public class AriaHelper {
      *            Element to check
      * @return String with the id of the element
      */
-    public static String ensureUniqueId(Element element) {
+    public static String ensureHasId(Element element) {
         assert element != null : "Valid Element required";
 
         String id = element.getId();
@@ -167,25 +167,22 @@ public class AriaHelper {
     }
 
     /**
-     * Moves an element out of sight. That way it is possible to have additional
-     * information for an assistive device, that is not in the way for visual
-     * users.
+     * Allows to move an element out of the visible area of the browser window.
      * 
-     * @param element
-     *            Element to move out of sight
-     */
-    public static void visibleForAssistiveDevicesOnly(Element element) {
-        element.addClassName(ASSISTIVE_DEVICE_ONLY_STYLE);
-    }
-
-    /**
-     * Clears the settings that moved the element out of sight, so it is visible
-     * on the page again.
+     * This makes it possible to have additional information for an assistive
+     * device, that is not in the way for visual users.
      * 
      * @param element
-     *            Element to clear the specific styles from
+     *            Element to move out of sight
+     * @param boolean assistiveOnly true when element should only be visible for
+     *        assistive devices, false to make the element visible for all
      */
-    public static void visibleForAll(Element element) {
-        element.removeClassName(ASSISTIVE_DEVICE_ONLY_STYLE);
+    public static void setVisibleForAssistiveDevicesOnly(Element element,
+            boolean assistiveOnly) {
+        if (assistiveOnly) {
+            element.addClassName(ASSISTIVE_DEVICE_ONLY_STYLE);
+        } else {
+            element.removeClassName(ASSISTIVE_DEVICE_ONLY_STYLE);
+        }
     }
 }
diff --git a/client/src/com/vaadin/client/ui/HandlesAriaCaption.java b/client/src/com/vaadin/client/ui/aria/HandlesAriaCaption.java
index fbbbbff462..50f83fdede 100644
--- a/client/src/com/vaadin/client/ui/HandlesAriaCaption.java
+++ b/client/src/com/vaadin/client/ui/aria/HandlesAriaCaption.java
@@ -14,7 +14,7 @@
  * the License.
  */
 
-package com.vaadin.client.ui;
+package com.vaadin.client.ui.aria;
 
 import com.google.gwt.user.client.Element;
 
@@ -29,14 +29,11 @@ public interface HandlesAriaCaption {
      * Called to bind the provided caption (label in HTML speak) element to the
      * main input element of the Widget.
      * 
+     * Binding should be removed from the main input field when captionElement
+     * is null.
+     * 
      * @param captionElement
      *            Element of the caption
      */
     void bindAriaCaption(Element captionElement);
-
-    /**
-     * Called to clear the binding to a caption from the main input element of
-     * the widget.
-     */
-    void clearAriaCaption();
 }
diff --git a/client/src/com/vaadin/client/ui/HandlesAriaInvalid.java b/client/src/com/vaadin/client/ui/aria/HandlesAriaInvalid.java
index ad75a265f9..05cb82b0d6 100644
--- a/client/src/com/vaadin/client/ui/HandlesAriaInvalid.java
+++ b/client/src/com/vaadin/client/ui/aria/HandlesAriaInvalid.java
@@ -14,7 +14,7 @@
  * the License.
  */
 
-package com.vaadin.client.ui;
+package com.vaadin.client.ui.aria;
 
 /**
  * Some Widgets need to handle the required handling for WAI-ARIA themselfs, as
@@ -29,5 +29,5 @@ public interface HandlesAriaInvalid {
      *            boolean, true when the element should be marked invalid, false
      *            otherwise
      */
-    void setInvalid(boolean invalid);
+    void setAriaInvalid(boolean invalid);
 }
diff --git a/client/src/com/vaadin/client/ui/HandlesAriaRequired.java b/client/src/com/vaadin/client/ui/aria/HandlesAriaRequired.java
index 66f76a7c44..9b18bfb4de 100644
--- a/client/src/com/vaadin/client/ui/HandlesAriaRequired.java
+++ b/client/src/com/vaadin/client/ui/aria/HandlesAriaRequired.java
@@ -14,7 +14,7 @@
  * the License.
  */
 
-package com.vaadin.client.ui;
+package com.vaadin.client.ui.aria;
 
 /**
  * Some Widgets need to handle the required handling for WAI-ARIA themselfs, as
@@ -28,5 +28,5 @@ public interface HandlesAriaRequired {
      * @param required
      *            boolean true when the element needs to be set as required
      */
-    void setRequired(boolean required);
+    void setAriaRequired(boolean required);
 }
diff --git a/client/src/com/vaadin/client/ui/checkbox/CheckBoxConnector.java b/client/src/com/vaadin/client/ui/checkbox/CheckBoxConnector.java
index 7c2052e6f1..85e4e5ee8b 100644
--- a/client/src/com/vaadin/client/ui/checkbox/CheckBoxConnector.java
+++ b/client/src/com/vaadin/client/ui/checkbox/CheckBoxConnector.java
@@ -69,7 +69,7 @@ public class CheckBoxConnector extends AbstractFieldConnector implements
                 blurHandlerRegistration);
 
         if (null != getState().errorMessage) {
-            getWidget().setInvalid(true);
+            getWidget().setAriaInvalid(true);
 
             if (getWidget().errorIndicatorElement == null) {
                 getWidget().errorIndicatorElement = DOM.createSpan();
@@ -88,10 +88,10 @@ public class CheckBoxConnector extends AbstractFieldConnector implements
             DOM.setStyleAttribute(getWidget().errorIndicatorElement, "display",
                     "none");
 
-            getWidget().setInvalid(false);
+            getWidget().setAriaInvalid(false);
         }
 
-        getWidget().setRequired(isRequired());
+        getWidget().setAriaRequired(isRequired());
         if (isReadOnly()) {
             getWidget().setEnabled(false);
         }
diff --git a/client/src/com/vaadin/client/ui/orderedlayout/AbstractOrderedLayoutConnector.java b/client/src/com/vaadin/client/ui/orderedlayout/AbstractOrderedLayoutConnector.java
index 9cda995160..cb6ad25e97 100644
--- a/client/src/com/vaadin/client/ui/orderedlayout/AbstractOrderedLayoutConnector.java
+++ b/client/src/com/vaadin/client/ui/orderedlayout/AbstractOrderedLayoutConnector.java
@@ -30,8 +30,8 @@ import com.vaadin.client.communication.StateChangeEvent;
 import com.vaadin.client.communication.StateChangeEvent.StateChangeHandler;
 import com.vaadin.client.ui.AbstractFieldConnector;
 import com.vaadin.client.ui.AbstractLayoutConnector;
-import com.vaadin.client.ui.AriaHelper;
 import com.vaadin.client.ui.LayoutClickEventHandler;
+import com.vaadin.client.ui.aria.AriaHelper;
 import com.vaadin.client.ui.layout.ElementResizeEvent;
 import com.vaadin.client.ui.layout.ElementResizeListener;
 import com.vaadin.shared.AbstractFieldState;