Show drop hints when dropping in empty Grid (#9353)

Also makes sure that the drop location and target row return something sensible in drop event.
Clarifies docs on drop location.

2 files changed, 32 insertions, 10 deletions

diff --git a/server/src/main/java/com/vaadin/ui/components/grid/GridDropEvent.java b/server/src/main/java/com/vaadin/ui/components/grid/GridDropEvent.java
index 80eab4d1fd..e6af56d66d 100644
--- a/server/src/main/java/com/vaadin/ui/components/grid/GridDropEvent.java
+++ b/server/src/main/java/com/vaadin/ui/components/grid/GridDropEvent.java
@@ -20,6 +20,7 @@ import java.util.Optional;
 
 import com.vaadin.shared.ui.dnd.DropEffect;
 import com.vaadin.shared.ui.grid.DropLocation;
+import com.vaadin.shared.ui.grid.DropMode;
 import com.vaadin.ui.AbstractComponent;
 import com.vaadin.ui.Grid;
 import com.vaadin.ui.dnd.DragSourceExtension;
@@ -43,19 +44,21 @@ public class GridDropEvent<T> extends DropEvent<Grid<T>> {
      * Creates a Grid row drop event.
      *
      * @param target
-     *         Grid that received the drop.
+     *            Grid that received the drop.
      * @param data
-     *         Map containing all types and corresponding data from the {@code
+     *            Map containing all types and corresponding data from the
+     *            {@code
      *         DataTransfer} object.
      * @param dropEffect
-     *         the desired drop effect
+     *            the desired drop effect
      * @param dragSourceExtension
-     *         Drag source extension of the component that initiated the drop
-     *         event.
+     *            Drag source extension of the component that initiated the drop
+     *            event.
      * @param dropTargetRow
-     *         Target row that received the drop.
+     *            Target row that received the drop, or {@code null} if dropped
+     *            on empty grid
      * @param dropLocation
-     *         Location of the drop within the target row.
+     *            Location of the drop within the target row.
      */
     public GridDropEvent(Grid<T> target, Map<String, String> data,
             DropEffect dropEffect,
@@ -68,10 +71,13 @@ public class GridDropEvent<T> extends DropEvent<Grid<T>> {
     }
 
     /**
-     * Get the row item source of this event.
+     * Get the row the drop happened on.
+     * <p>
+     * If the drop was not on top of a row (see {@link #getDropLocation()}),
+     * then returns an empty optional.
      *
-     * @return The optional row item if the event was originated from a row,
-     * otherwise an empty optional.
+     * @return The row the drop happened on, or an empty optional if dropped on
+     *         the in grid but not on top of any row, like to an empty grid
      */
     public Optional<T> getDropTargetRow() {
         return Optional.ofNullable(dropTargetRow);
@@ -79,8 +85,13 @@ public class GridDropEvent<T> extends DropEvent<Grid<T>> {
 
     /**
      * Get the location of the drop within the row.
+     * <p>
+     * <em>NOTE: when dropped on an empty grid, or when {@link DropMode#ON_TOP}
+     * is used and the drop happened on empty space after last row, the location
+     * will be {@link DropLocation#EMPTY}.</em>
      *
      * @return Location of the drop within the row.
+     * @see GridDropTarget#setDropMode(DropMode)
      */
     public DropLocation getDropLocation() {
         return dropLocation;
diff --git a/server/src/main/java/com/vaadin/ui/components/grid/GridDropTarget.java b/server/src/main/java/com/vaadin/ui/components/grid/GridDropTarget.java
index 07c81c9981..b86ca13080 100644
--- a/server/src/main/java/com/vaadin/ui/components/grid/GridDropTarget.java
+++ b/server/src/main/java/com/vaadin/ui/components/grid/GridDropTarget.java
@@ -55,6 +55,17 @@ public class GridDropTarget<T> extends DropTargetExtension<Grid<T>> {
 
     /**
      * Sets the drop mode of this drop target.
+     * <p>
+     * Note that when using {@link DropMode#ON_TOP}, and the grid is either
+     * empty or has empty space after the last row, the drop can still happen on
+     * the empty space, and the {@link GridDropEvent#getDropTargetRow()} will
+     * return an empty optional.
+     * <p>
+     * When using {@link DropMode#BETWEEN} or
+     * {@link DropMode#ON_TOP_OR_BETWEEN}, and there is at least one row in the
+     * grid, any drop after the last row in the grid will get the last row as
+     * the {@link GridDropEvent#getDropTargetRow()}. If there are no rows in the
+     * grid, then it will return an empty optional.
      *
      * @param dropMode
      *            Drop mode that describes the allowed drop locations within the