Add mobile html5 dnd support using polyfill (#9282)

First step of mobile DND support.

- Add mobile html5 dnd support using polyfill
- Adds a switch for enabling mobile html5 dnd support
- Adds polyfill only when needed
- Ignore native Android Chrome drag start because doesn't work properly
(no dragend event fired)
- Add documentation on enabling mobile HTML5 DnD support
- Add mention of drag-drop-polyfill license
- Fixed issue in polyfill when not using "snapback"
- Add mention of forked polyfill

Fixes #9174

1 files changed, 44 insertions, 6 deletions

diff --git a/documentation/advanced/advanced-dragndrop.asciidoc b/documentation/advanced/advanced-dragndrop.asciidoc
index 6390eff201..1e6a3af86e 100644
--- a/documentation/advanced/advanced-dragndrop.asciidoc
+++ b/documentation/advanced/advanced-dragndrop.asciidoc
@@ -17,10 +17,6 @@ the other location is a common way to move, copy, or associate objects. For
 example, most operating systems allow dragging and dropping files between
 folders or dragging a document on a program to open it. Framework version 8.1 adds support for https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API[HTML5 drag and drop] features. This makes it possible to set components as drag sources that user can drag and drop, or to set them as drop targets to drop things on.
 
-[NOTE]
-====
-Note that the HTML5 drag and drop feature is not supported on touch devices.
-====
 
 == Drag Source
 
@@ -145,8 +141,6 @@ TODO Add an example of drop criteria
 When dragging data over a drop target and the drag over criteria passes, a style name is applied to indicate that the element accepts drops. This style name is the primary style name with `-drag-center` suffix, e.g. `v-label-drag-center`.
 
 
-===
-
 ////
 TODO add back when supported with new API ?
 [[advanced.dragndrop.external]]
@@ -166,6 +160,50 @@ compatible browser, such as Mozilla Firefox 3.6 or newer.
 
 ////
 
+[[advanced.dragndrop.mobile]]
+== Mobile Drag And Drop Support
+
+The HTML 5 Drag and Drop API is not yet supported by mobile browsers. To enable HTML5 DnD support on mobile devices, we have included
+an link:https://github.com/timruffles/ios-html5-drag-drop-shim/tree/rewrite:[external Polyfill]. Please note that this Polyfill is under the BSD 2 License.
+
+By default, the mobile DnD support is disabled, but you can enable it any time for a [classname]#UI#. Starting from the request where the support was enabled, all the added [classname]#DragSourceExtension#, [classname]#DropTargetExtension# and their subclasses will also work on mobile devices for that UI. The Polyfill is only loaded when the user is using a touch device.
+
+[source, java]
+----
+public class MyUI extends UI {
+    protected void init(VaadinRequest request) {
+        setMobileHtml5DndEnabled(true);
+    }
+}
+----
+
+[NOTE]
+====
+When disabling the support, you need to also remove all the [classname]#DragSourceExtension#, [classname]#DropTargetExtension# and their subclasses that were added when the mobile DnD support was enabled.
+====
+
+=== CSS Style Rules
+
+The Polyfill allows you to apply custom styling to enhance the user experience on touch devices. It is important to remember that these customizations are only used when the polyfill is loaded, and not possible for desktop DnD operations.
+
+The drag image can be customized using the `dnd-poly-drag-image` class name. You must NOT wrap the class rule with e.g. `.valo`, since that is not applied to the drag image element. The following styling can be used to make the drag image opaque and "snap back" when the user did not drop to a valid dropzone:
+
+[source, css]
+====
+.dnd-poly-drag-image {
+    opacity: .5 !important;
+}
+
+.dnd-poly-drag-image.dnd-poly-snapback {
+    transition-property: transform, -webkit-transform !important;
+    transition-duration: 200ms !important;
+    transition-timing-function: ease-out !important;
+}
+====
+
+More details can be found from the link:https://github.com/timruffles/ios-html5-drag-drop-shim/tree/rewrite:[Polyfill] website.
+
+
 [[advanced.dragndrop.grid]]
 == Drag and Drop Rows in Grid